| name | xurl-rs |
| description | Drive the X (Twitter) API from the command line via `xr`, the xurl-rs CLI. Use when the user wants to post or thread, reply, quote, delete, like, repost, bookmark, follow, mute, block, send DMs, search recent posts, read a timeline or mentions, look up a user, upload media, stream filtered tweets, hit a raw `/2/...` endpoint, manage OAuth2 / OAuth1 / Bearer auth, register multiple X apps, inspect token state, check API usage caps, or validate a tweet/user JSON payload against the typed response schema. Triggers on "post to X", "post to Twitter", "tweet from CLI", "X API call", "OAuth2 X", "xurl", "xr command", "search tweets", "send DM", "follow on X". |
xurl-rs (xr)
xr is a Rust CLI for the X (Twitter) API. It ships ~30 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 an agent-native output envelope.
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
/ block / unblock / mute / unmute / dm / media upload) hits production state.
Before any write op:
- 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.
- Confirm scope with the user before issuing the live call when the action is destructive (
delete, block,
unfollow, dm, post to anything besides a test thread the user already named).
- 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, 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 three self-introspection commands. Reach for them before reading anything in references/:
xr examples
xr <command> --help
xr schema --list --output json
xr schema --command post --output json
xr schema --envelope --output json
xr auth status --output json
For full read-only-probes-are-always-safe rules, see
references/self-introspection.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.
| Script | Use for |
|---|
scripts/dry-run-gate.sh [--yes] -- xr <write-verb> [args] | Every write op. Runs --dry-run preflight, refuses on would_succeed: false, prompts on TTY or honors --yes, then execs the live call. |
scripts/paginate.sh [--max-pages N] -- xr <list-verb> | Every cursor-paginated read. Streams .data[]? as compact JSONL, follows meta.next_token, caps at --max-pages. |
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
- Never invent X API endpoints, scopes, billing tiers, or rate-limit numbers. They change. See
references/escalation.md for the lookup order.
- 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.
- 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.
- 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. No confirmation needed.
Common flag patterns to apply across calls
--output json (or XURL_OUTPUT=json) — machine-readable on every command.--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.
Full agent-flag matrix and env-var precedence: references/agent-flags.md.
Verifying the install
xr version
xr --help
xr auth status
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).
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.
- references/agent-flags.md — output formats, pagination, dry-run, env-var precedence, exit
codes.
- references/output-envelope.md — the
ok / dry_run / error envelope, typed
reasons, exit-code matrix.
- references/x-api-essentials.md — drift-resistant pointers into the X API (auth
scopes, tiers, rate limits).
Templates
Scripts
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) live in AGENTS.md. Don't
conflate the two.
