feat: initial v0.1 — thin X/Twitter scraping CLI

x-cli is a small, sharp Go command-line tool that scrapes and lightly
automates X (formerly Twitter) from an imported browser session. One
static binary, built-in throttling, keychain-stored cookies, no server,
no database, no MCP.

Scope (v0.1):
  - auth import | status | logout       cookie-only auth, no credential login
  - doctor                               endpoints, session, egress ASN, TLS
  - config get | path
  - profile get <user>                   end-to-end (UserByScreenName)
  - tweets | search | followers | following | thread | media | monitor
    scaffolded as stubs so the command tree matches SKILL.md from day one
  - grow follow-engagers | follow-by-keyword
    dry-run by default, hard mutation budget, refuses cloud ASN

Transport (api/):
  - GraphQL + REST helpers keyed off endpoints.yaml (data, not code —
    patch X's rotating query IDs without a rebuild)
  - Per-endpoint token bucket for reads
  - Global mutation state: min_gap + jitter + daily cap (date-keyed so
    the counter resets correctly across year boundaries)
  - Slot reservation under lock before sleep, so two concurrent callers
    cannot both fire within one min_gap window
  - Autopause on x-rate-limit-reset and on consecutive error clusters
  - Adaptive backoff for 5xx/net errors, clamped to time.Duration
  - Deterministic BFS cursor walker (sorted keys) so paginated reads
    return the same cursor on every run
  - Set-Cookie rotation with an allowlist and deletion-directive guard
    so a single bad response cannot nuke a live session
  - Typed errors (AuthError, RateLimitError, NotFoundError, APIError
    with body truncation, NetworkError, BudgetExhaustedError)
  - Client protects session with an RWMutex

Storage (internal/store/):
  - OS keychain primary via go-keyring
  - AES-256-GCM file fallback with machine-id-derived key and an AAD
    tag bound to the format version. Atomic write via temp + rename +
    fsync + explicit chmod so a crash mid-write cannot corrupt a
    previously valid session. README is honest about the fallback being
    obfuscation, not encryption.

Skill (skills/x-cli/):
  - SKILL.md with the command tree (the CLI is the skill; no MCP)
  - references/{auth,throttle,endpoints}.md

Docs (docs/):
  - comparison-xactions.md: detail-level diff against nirholas/XActions
    with file:line citations, focused on auth posture

CI (.github/workflows/ci.yml):
  - ubuntu + macos matrix, go vet, go build, go test -race with
    coverage, go mod tidy drift check
  - cross-compile matrix: linux/amd64, linux/arm64, darwin/amd64,
    darwin/arm64, windows/amd64

Tests:
  - api/ 76.9% coverage, internal/store/ 69.8% coverage
  - Concurrent mutation race regression test
  - Deterministic cursor walker regression test
  - Set-Cookie rotation + deletion-directive hardening tests
  - Race-clean under go test -race

Credits:
  - Endpoint map cross-referenced from d60/twikit (MIT) and
    the-convocation/twitter-scraper (MIT)
  - Reference layout inspired by lroolle/atlas-cli and cli/cli
  - nirholas/XActions used as a reference only (BSL-1.1); no code copied

Author: lroolle

.github/workflows/ci.yml

@@ -0,0 +1,88 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+          cache: true
+
+      - name: Module tidy check
+        run: |
+          go mod tidy
+          git diff --exit-code go.mod go.sum
+
+      - name: Vet
+        run: go vet ./...
+
+      - name: Build
+        run: go build -v ./...
+
+      - name: Test (race, coverage)
+        run: go test -race -count=1 -coverprofile=coverage.out -covermode=atomic ./...
+
+      - name: Coverage summary
+        run: go tool cover -func=coverage.out
+
+      - name: Upload coverage artifact
+        if: matrix.os == 'ubuntu-latest'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.out
+          retention-days: 7
+
+  cross-compile:
+    name: cross (${{ matrix.goos }}/${{ matrix.goarch }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { goos: linux,   goarch: amd64 }
+          - { goos: linux,   goarch: arm64 }
+          - { goos: darwin,  goarch: amd64 }
+          - { goos: darwin,  goarch: arm64 }
+          - { goos: windows, goarch: amd64 }
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.23'
+          cache: true
+
+      - name: Build ${{ matrix.goos }}/${{ matrix.goarch }}
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: '0'
+        run: |
+          mkdir -p dist
+          ext=""
+          if [ "$GOOS" = "windows" ]; then ext=".exe"; fi
+          out="dist/x-${GOOS}-${GOARCH}${ext}"
+          go build -trimpath -ldflags "-s -w" -o "$out" ./cmd/x
+          ls -la "$out"

.gitignore

@@ -0,0 +1,14 @@
+bin/
+dist/
+*.test
+*.out
+.env
+.env.*
+!.env.example
+~/.config/x-cli/
+session.enc
+.DS_Store
+.idea/
+.vscode/
+coverage.out
+reference/

LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 x-cli authors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

Makefile

@@ -0,0 +1,41 @@
+BINARY      := x
+PKG         := github.com/lroolle/x-cli
+VERSION     := $(shell git describe --tags --always --dirty 2>/dev/null || echo dev)
+LDFLAGS     := -s -w -X $(PKG)/internal/version.Version=$(VERSION)
+GOFLAGS     := -trimpath
+
+.PHONY: all build install tidy test test-race cover lint vet clean run ci
+
+all: build
+
+build:
+	CGO_ENABLED=0 go build $(GOFLAGS) -ldflags '$(LDFLAGS)' -o bin/$(BINARY) ./cmd/x
+
+install:
+	CGO_ENABLED=0 go install $(GOFLAGS) -ldflags '$(LDFLAGS)' ./cmd/x
+
+tidy:
+	go mod tidy
+
+test:
+	go test -count=1 ./...
+
+test-race:
+	go test -race -count=1 ./...
+
+cover:
+	go test -race -count=1 -coverprofile=coverage.out -covermode=atomic ./...
+	go tool cover -func=coverage.out | tail -20
+
+lint: vet
+
+vet:
+	go vet ./...
+
+clean:
+	rm -rf bin/ dist/ coverage.out
+
+run: build
+	./bin/$(BINARY)
+
+ci: vet test-race build

README.md

@@ -0,0 +1,91 @@
+# x-cli
+
+A small, sharp command-line tool for scraping and lightly automating X
+(formerly Twitter) from your own logged-in session. One static Go binary,
+built-in throttling, keychain-stored cookies, no server, no database, no MCP.
+
+> **Heads-up.** x-cli talks to X's internal web endpoints, not a supported
+> public API. Your real account cookie is the identity. This is not an official
+> client, there is no SLA, and mutations (follow / unfollow / like) can get
+> your account rate-limited, action-blocked, or suspended. Reading public data
+> is low risk. Mutating at scale is not. Read `skills/x-cli/references/auth.md`
+> before you run anything with `grow`.
+
+## What it does
+
+- `x profile get <user>` — scrape profile
+- `x followers <user>` / `x following <user>` — paginated scraping
+- `x tweets list <user>` / `x tweets get <id>` — user timeline and single tweet
+- `x search posts <query>` / `x search users <query>` — scrape search results
+- `x thread unroll <id>` — reassemble a thread from a root tweet
+- `x media download <id|url>` — download images and videos from a tweet
+- `x monitor account <user>` — poll a profile/timeline and stream deltas
+- `x grow follow-engagers <tweet-id>` — follow likers/retweeters of a tweet (mutation, dry-run by default)
+- `x grow follow-by-keyword <query>` — follow authors matching a query (mutation, dry-run by default)
+
+## What it is not
+
+- Not a wrapper over X's official v2 API. No API keys, no OAuth.
+- No MCP server. The CLI *is* the skill — see `skills/x-cli/SKILL.md`.
+- No Chrome extension, no dashboard, no database, no payments.
+- No credential/password login. Cookie import only.
+
+## Install
+
+```
+make build
+./bin/x auth import
+./bin/x doctor
+./bin/x profile get jack
+```
+
+## Auth
+
+Log into x.com in your real browser, DevTools → Application → Cookies, copy
+`auth_token` and `ct0`, then:
+
+```
+x auth import
+# paste: auth_token=...; ct0=...; twid=u%3D...
+```
+
+**Where the cookie lives.** x-cli tries the OS keychain first (`go-keyring`:
+Keychain on macOS, libsecret on Linux, Credential Manager on Windows). If the
+keychain is unavailable — headless boxes, containers, CI, Linux without a
+Secret Service daemon — x-cli falls back to an AES-256-GCM file at
+`$XDG_CONFIG_HOME/x-cli/session.enc` with mode `0600`.
+
+**Be honest about the fallback.** The file's encryption key is derived from a
+machine-stable seed (`/etc/machine-id` or the hostname), not from a passphrase
+you control. Its job is to keep the cookie from being casually visible in
+plaintext and to fail-closed on a file copied between machines. It is **not**
+a defense against an attacker with read access to your home directory — they
+can reproduce the key and decrypt it. Treat the keychain path as the real
+at-rest protection; treat the file fallback as obfuscation.
+
+`x auth logout` removes both the keychain entry and the file fallback.
+
+## Throttle
+
+Built in. Per-endpoint token buckets; mutation commands have a hard daily
+budget, minimum action gap, and jitter. Configured in `endpoints.yaml`
+alongside the query IDs. Mutations require `--apply`; default is dry-run.
+
+## Layout
+
+```
+cmd/         cobra commands
+api/         HTTP transport, endpoints, throttle, auth
+internal/    cmdutil, keychain store, TLS fingerprint, version
+skills/      agentic skill (CLI as skill)
+endpoints.yaml   query IDs + features + per-endpoint budgets
+```
+
+## Credits
+
+Endpoint map cross-referenced from [`twikit`](https://github.com/d60/twikit)
+and [`twitter-scraper`](https://github.com/the-convocation/twitter-scraper),
+both MIT. Reference layout inspired by
+[`atlas-cli`](https://github.com/lroolle/atlas-cli) and
+[`gh`](https://github.com/cli/cli). `XActions` is a reference only; no code
+was copied (BSL-1.1).

api/auth.go

@@ -0,0 +1,91 @@
+package api
+
+import (
+	"context"
+	"encoding/json"
+	"net/http"
+	"strings"
+)
+
+// Session holds the cookies and derived tokens for one authenticated user.
+// All fields are opaque to callers except through the methods on *Client.
+type Session struct {
+	Cookies map[string]string
+	User    *User
+}
+
+type User struct {
+	ID       string `json:"id_str"`
+	Username string `json:"screen_name"`
+	Name     string `json:"name"`
+}
+
+// ParseCookieString accepts a browser-exported header like
+//
+//	auth_token=abc; ct0=def; twid=u%3D123
+//
+// and returns a cookie map. Empty names and empty values are dropped so
+// that pasting stale `document.cookie` output does not produce `name=`
+// entries that X's gateway may reject. Values are NOT URL-decoded — `twid`
+// and friends are echoed raw on the wire.
+func ParseCookieString(s string) map[string]string {
+	out := map[string]string{}
+	for _, pair := range strings.Split(s, ";") {
+		pair = strings.TrimSpace(pair)
+		if pair == "" {
+			continue
+		}
+		idx := strings.IndexByte(pair, '=')
+		if idx <= 0 {
+			continue
+		}
+		name := strings.TrimSpace(pair[:idx])
+		val := strings.TrimSpace(pair[idx+1:])
+		if name == "" || val == "" {
+			continue
+		}
+		out[name] = val
+	}
+	return out
+}
+
+// RequireAuthCookies returns an AuthError if the required cookies are absent.
+func RequireAuthCookies(cookies map[string]string) error {
+	if cookies["auth_token"] == "" {
+		return &AuthError{Msg: "missing auth_token cookie"}
+	}
+	if cookies["ct0"] == "" {
+		return &AuthError{Msg: "missing ct0 (CSRF) cookie"}
+	}
+	return nil
+}
+
+// VerifyCredentials hits /1.1/account/verify_credentials.json and returns the
+// user if the session is alive, or an AuthError otherwise.
+func (c *Client) VerifyCredentials(ctx context.Context) (*User, error) {
+	url := c.endpoints.Bases.REST + "/1.1/account/verify_credentials.json"
+	resp, err := c.request(ctx, "GET", url, nil, requestOpts{authenticated: true, endpointName: "verifyCredentials"})
+	if err != nil {
+		return nil, err
+	}
+	defer resp.Body.Close()
+
+	if resp.StatusCode == http.StatusUnauthorized || resp.StatusCode == http.StatusForbidden {
+		return nil, &AuthError{Msg: "session invalid or expired", Status: resp.StatusCode}
+	}
+	if resp.StatusCode >= 400 {
+		return nil, &APIError{Endpoint: "verifyCredentials", Status: resp.StatusCode}
+	}
+
+	var u User
+	if err := json.NewDecoder(resp.Body).Decode(&u); err != nil {
+		return nil, err
+	}
+	if u.ID == "" {
+		return nil, &AuthError{Msg: "verify_credentials returned empty user"}
+	}
+	c.sessionMu.Lock()
+	c.session.User = &u
+	c.sessionMu.Unlock()
+	return &u, nil
+}