Xurl Rs

xurl-rs (xr)

xr is a Rust CLI for the X (Twitter) API. It ships 27 high-level shortcut commands, a raw curl-style mode for any /2/... endpoint, OAuth1 / OAuth2-PKCE / Bearer auth with a multi-app token store at ~/.xurl, chunked media upload, streaming, typed JSON-schema responses, and typed error envelopes with a next_step an agent can act on.

The binary self-introspects. Treat it as the source of truth: this skill routes you to the binary's helpers and provides the workflow patterns that the binary can't describe on its own.

Hard guardrail: production credentials

The xr binary on the user's machine is configured against real X API credentials, not a sandbox. Every write operation (post / reply / quote / delete / like / unlike / repost / unrepost / bookmark / unbookmark / follow / unfollow / mute / unmute / dm / media upload) hits production state.

Before any write op:

1. Use --dry-run first to surface input validation errors and confirm intent. Every write verb emits a typed status: "dry_run" envelope when --output json and --dry-run are both set; check would_succeed: true and exit_code: 0. Dry-run validates inputs only: not credentials, not the filesystem, and not the verb's own confirmation gate. Only the three verbs with no inverse (delete, auth clear, auth apps remove) gate themselves and need --force even for the preflight when there is no TTY; every other write verb, mute and unfollow included, takes no --force (passing it is invalid-args).
2. Confirm scope with the user before issuing the live call when the action is destructive (delete, unfollow, mute, dm, post to anything besides a test thread the user already named).
3. Prefer --output json with --no-interactive so failures arrive as structured envelopes you can act on.

Read ops (read, search, whoami, user, timeline, mentions, bookmarks, likes, following, followers, dms, usage, usage credits, media status, auth status, schema, validate, examples, version) ignore --dry-run and are safe to run without confirmation.

Quick start: let the binary teach you

The binary ships five self-introspection commands. Reach for them before reading anything in references/:

xr examples                          # curated invocation gallery, ~130 lines, every major workflow
xr <command> --help                  # 3-5 examples per command + full flag matrix
xr schema --list                     # 35 typed response shapes, one per command
xr schema post --output json         # JSON Schema for a single response type
xr schema --envelope --output json   # the ok / dry_run / error envelope variants and every error key
xr auth status --output json         # a bare array of registered apps; read it through .[]

For full read-only-probes-are-always-safe rules, see references/self-introspection.md.

Read the exit code, then the document

Under --output json, a success is the X API document itself on stdout (data, plus meta / includes / errors when the API sent them) with no status key; only local verbs (auth …, validate, skill …) add status: "ok". A failure is a status: "error" envelope on stderr with a non-zero exit, a closed-set kebab-case reason, an exit_code, and, when a recovery exists, a next_step object. Exit 77 means no usable credential; its next_step.action is one of register-app / sign-in / select-app / inspect-store / enroll-app, and a command is safe to run verbatim while a template needs values only the user has:

xr auth status --output json                 # [ {...}, ... ]; each entry carries client_id_hint and bearer
xr whoami --output json 2>&1 >/dev/null      # the failure itself, carrying next_step

Branch on the exit code first, then on reason and next_step.action; never guess a credential fix, and never treat a missing status on a 0 exit as an error. Full contract, catalog, and the exit-77 recipe: references/output-envelope.md.

Deterministic helpers (scripts/)

The bundle ships two shellcheck-clean scripts that encode the rules the references describe. Prefer them when you can: they enforce mechanically what the prose only requests.

Both auto-detect jaq (preferred) or jq. When neither is installed, they emit a PM-aware install advice ranked by what's already on the system. Install path after xr skill install claude_code (or the host equivalent) is ~/.claude/skills/xurl-rs/scripts/. Full contract: scripts/README.md.

Routing table

Iron rules

1. Never invent X API endpoints, scopes, billing tiers, or rate-limit numbers. They change. See references/escalation.md for the lookup order.
2. Never run a live write op without confirming scope with the user first, OR without a successful --dry-run pass against the exact same flags first.
3. Never paste credentials into chat, commits, PR bodies, or shell history. Pass secrets through env vars (XURL_BEARER_TOKEN, --client-secret "$(op read op://...)"); never inline them.
4. Read-only probes are always fine: xr --help, xr <cmd> --help, xr examples, xr schema ..., xr validate < file.json, xr auth status, xr version, xr usage, xr usage credits. No confirmation needed.

Common flag patterns to apply across calls

• --output json (or XURL_OUTPUT=json): machine-readable on every command. --output jsonl prints the same whole document, not one record per line; get per-record lines with jaq -c '.data[]?' (or scripts/paginate.sh).
• --no-interactive: fail with a structured envelope instead of prompting.
• --no-pager: documented no-op, safe to always pass.
• --quiet: suppress human-only banners (errors still go to stderr).
• --timeout 30 (the default): bump for streaming / slow networks.
• -n <1..100> / --limit: page size for list verbs (search floors at 10, the API's minimum); --cursor <token> from meta.next_token for the next page.

Full agent-flag matrix and env-var precedence: references/agent-flags.md.

Verifying the install

xr version             # prints "xr 3.2.0"; this bundle describes the 3.2.0 release
xr --help              # full surface
xr auth status --output json | jaq -r '.[].name'       # which apps are registered

A build from the development branch ahead of the 3.2.0 release may add commands and reshape local-verb documents; xr --help is authoritative for the surface, and the bundle published beside that release describes its contract.

If xr is not on $PATH, install it from https://github.com/brettdavies/xurl-rs/releases, or refresh this bundle with xr skill update claude_code (or whichever host; xr skill update --all refreshes every known host, cloning into the ones that had no installation).

Reference index

• references/escalation.md: when stuck, lookup order, iron rules, halt-vs-continue, worked examples.
• references/self-introspection.md: let the binary teach you (examples, schema, validate, usage).
• references/auth-modes.md: OAuth2 PKCE (browser + headless), OAuth1, Bearer, multi-app token store, the auth status apps shape, what to do on exit 77.
• references/agent-flags.md: output formats (and what jsonl really emits), pagination and clamps, dry-run, verbose, env-var precedence, exit codes.
• references/output-envelope.md: the four document kinds (API document / ok / dry_run / error), the closed-set reason catalog, next_step, the exit-77 recipe, exit-code matrix, which schema validates which document.
• references/x-api-essentials.md: drift-resistant pointers into the X API (auth scopes, tiers, rate limits, per-category doc URLs).

Templates

• templates/oauth2-setup.md: first-time OAuth2 (browser or headless), verify with xr auth status.
• templates/post-reply-thread.md: compose, capture id, thread; leads with scripts/dry-run-gate.sh.
• templates/search-and-process.md: xr search --output json | jaq -c '.data[]'; leads with scripts/paginate.sh.
• templates/media-upload.md: chunked upload, attach --media-id via the gate.

Scripts

• scripts/dry-run-gate.sh: preflight → confirm → live wrapper for every xr write op.
• scripts/paginate.sh: cursor-pagination loop for any xr list-style verb.
• scripts/README.md: full contract, exit codes, invocation patterns, jaq/jq fallback notes.

Producer-side notes

This file is the consumer entry point and is loaded into the agent's context when the skill activates. Producer-side notes for agents working on this bundle (release flow, branch model, CI, the contract harness that verifies every claim above against a real binary) live in AGENTS.md. Don't conflate the two.