bird

bird is a Rust CLI that wraps the X (Twitter) v2 API with capabilities xurl does not have: a SQLite entity store with per-endpoint TTL, watchlist monitoring, thread reconstruction, API usage with local cost ledger, structured error envelopes with split exit codes (0 / 1 / 2 / 77 / 78), JSON Schema documents for every output shape, search ergonomics (--sort likes --min-likes --pages), and bird doctor self-diagnostics covering xurl status, auth state, command availability, and store health.

bird does not implement HTTP or OAuth itself. Every API call shells out to xr (xurl-rs) or xurl (Go fallback) at runtime. Discovery order: BIRD_XURL_PATH env → xr on $PATH → xurl on $PATH. Minimum xurl version: 1.0.3.

Sibling skills — install if you don't have them

Two companion skills cover ground this skill deliberately does NOT duplicate. Reach for them when the task crosses their line.

Routing rule: if the task is about auth, the raw xr write-op transport, the X API endpoint shape, or what scope a verb requires — that question belongs to one of those skills. This skill covers the value bird adds on top of them.

Hard guardrail — production credentials

The installed bird binary on the user's machine runs against real X API credentials (token storage lives in xurl's ~/.xurl, not in bird). Every write op (tweet, reply, like, unlike, repost, unrepost, follow, unfollow, block, unblock, mute, unmute, dm, delete, post, put) hits production state.

Before any write op:

1. Run with --dry-run first. bird prints the would-be request without sending and emits a typed envelope under --output json.
2. Confirm scope with the user before issuing the live call when the action is destructive (delete, block, unfollow, dm to anyone unfamiliar, post/tweet to anything besides a thread the user already named).
3. Prefer --output json with --no-interactive so failures arrive as a structured envelope you can act on instead of prompting on stdin.

bird ships an explicit confirmation gate for no-TTY callers: a write op without --force/--yes exits 2 (requires-confirmation) rather than hanging. See scripts/write-op-gate.sh below for the wrapper.

Read ops (me, bookmarks, profile, search, thread, get, watchlist list, watchlist fetch, usage, cache stats, doctor, schema) are safe to run without confirmation.

Quick start — let the binary teach you

bird ships self-introspection on every subcommand. Reach for these before reading anything in references/:

bird --examples                            # curated invocation gallery for the root binary
bird <subcommand> --examples               # per-subcommand examples; works on every verb
bird <subcommand> --help                   # full flag matrix
bird schema --list --output json           # all output schema names: bookmarks, search, thread, profile, doctor, usage, watchlist, raw-get, success-envelope, error-envelope
bird schema <name> --output json           # full JSON Schema 2020-12 document for one shape
bird doctor --output json                  # xurl path/version, auth state, per-command availability, cache health
bird doctor <subcommand>                   # scoped diagnostics for one command

The output of bird doctor IS the answer to "is the environment ready?" — xurl.available, auth.authenticated, cache.healthy, and a per-command available map with a reason field on every false. Trust the report over the README.

Routing table

Iron rules

1. Never invent X API endpoints, OAuth scopes, billing tiers, or rate-limit numbers. They change and they live in the x-api companion skill or https://docs.x.com/...md. See references/escalation.md for the full 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, PRs, or shell history. bird does not store tokens; xurl does. Re-auth through bird login (delegates to xurl) or xr auth oauth2. Pass any inline secret through env vars ($(op read op://...)).
4. Never re-implement xr functionality inside bird workflows. If a task needs raw HTTP, streaming, OAuth1 signing, or media upload — that's xr's job. Defer to the xurl-rs skill.
5. Read-only probes are always fine without asking the user: bird --help, bird <cmd> --help, bird --examples, bird <cmd> --examples, bird schema ..., bird doctor, bird cache stats, bird usage --local, bird watchlist list. Run them as needed.

Common flag patterns

Every subcommand inherits these globals. Each binds to a BIRD_* env var so non-interactive callers can configure bird without touching argv. Full matrix → references/agent-flags.md.

Two env vars without flag pairs:

• BIRD_XURL_PATH — override transport discovery with a direct path to an xr or xurl binary.
• NO_COLOR=1 — strip ANSI color (industry standard; same effect as --color never).

Scripts

For paginating bird's list-style reads, you may use either:

• bird's own --limit + --cursor flags directly (responses surface meta.next_cursor), OR
• xurl-rs's paginate.sh if installed — it works against bird identically because both emit the same meta.next_* shape on --output json.

Full contract: scripts/README.md.

Verifying the install

bird --version                              # prints "bird X.Y.Z"
bird doctor --output json                   # xurl.available + auth.authenticated + cache.healthy
bird schema --list --output json            # 10 schema names land in .data[]

If xurl.available: false, the xurl-rs binary is missing — install it from https://github.com/brettdavies/xurl-rs/releases (or brew install brettdavies/tap/xurl-rs) and re-run bird doctor. If auth.authenticated: false, run bird login to bounce through xurl's OAuth2 PKCE flow.

Reference index

• references/escalation.md — when stuck: ordered lookup (bird → xr → x-api → official docs), iron rules, halt-vs-continue, worked examples.
• references/cache-modes.md — --refresh vs --no-cache vs --cache-only, TTL behavior, per-endpoint coverage, the --cache-only replay trick for offline analysis.
• references/error-envelope.md — JSON error shape (kind, exit_code, optional command/status/reason), the 0/1/2/77/78 exit-code split, mapping symptoms to fixes.
• references/usage-and-cost.md — bird usage, --sync, --local, --since, cost-ledger semantics, when to look at bird's local view vs the X API's authoritative one.
• references/agent-flags.md — full global-flag matrix, env-var precedence, output-format decision tree.
• references/schemas.md — the 10 schema names, embedded JSON Schema 2020-12 documents, how to pin against https://bird.dev/schema/<name>-v1.json, validation recipes.
• references/skill-install.md — bird skill install <host> mechanics, the hardened clone, supported hosts, dry-run.
• references/xr-bridge.md — what bird delegates to xr, the BIRD_XURL_PATH override, when to reach for the xurl-rs skill instead.

Templates

• templates/cached-search.md — bird search with sort/min-likes/pages and cache-mode selection. Worked example covering "the same query repeated through the day" cost optimization.
• templates/watchlist-monitor.md — bird watchlist add → fetch polling loop with cron-friendly --output jsonl and --no-interactive flags.

Producer-side notes

This file is the consumer entry point loaded into the agent's context when the skill activates. Producer-side notes for agents working on this bundle (release flow, branch model, CI guards) live in AGENTS.md. Don't conflate the two.