Crate bird 

bird library surface — internal test infrastructure only.

bird is distributed as a binary; the library surface is unstable and intended for internal test infrastructure only. External consumers should shell out to the bird binary, not import this crate.

Concrete invocation patterns — run_argv, run_with_paths against a TempDir-backed ResolvedPaths, captured writers, parsed JSON envelopes, parallel fixtures — live under examples/ and mirror the shapes used by tests/common/mod.rs and tests/parallel_run.rs. They are reference code for someone debugging the in-process test surface, not an endorsement of the library as a downstream API.

Modules

bookmarks

Curated bookmarks command: GET /2/users/{id}/bookmarks with pagination, max_results=100.

config

Config load with priority: command args > config file > env > default (build-in).

cost

Cost estimation and stderr display for X API billing. Stateless: estimates cost per response, displays to stderr. No persistent tracking (Plan 4).

db

Entity store: SQLite-backed entity storage with usage tracking. BirdDb is the application database – entities (tweets, users), bookmarks, raw responses, and usage data. Store failures are never fatal: the Option<BirdDb> pattern degrades to API-only mode.

doctor

bird doctor: living view of xurl status, auth state, command availability, and entity store health.

error

Structured error type and envelope mapping for the bird CLI.

fields

Canonical X API v2 field sets. Single source of truth for all commands.

login

Headless OAuth2 PKCE login flow.

output

Terminal output: color mode, output format, success/error envelopes, and styled helpers.

profile

Profile command: look up an X user by username, display JSON.

raw

Raw request layer: HTTP method + path (with param substitution), query/body, output.

requirements

Central command requirements: which auth types each command accepts. Used by execution, doctor (availability), and auth_flag mapping for xurl.

schema

Path template resolution with param substitution.

schema_print

bird schema subcommand: runtime-discoverable JSON Schemas for bird’s output shapes.

search

Search command: query building, pagination, filtering, sorting, JSON output.

skill_install

bird skill install <host> — clone the bird skill bundle into a host’s canonical skills directory using a build-generated host map and a hardened git clone invocation. The companion bird skill update <host> removes the destination and re-clones.

thread

Thread command: reconstruct a conversation thread from a tweet ID. Two-step fetch: get root tweet for conversation_id, then search for all replies.

transport

xurl subprocess transport layer.

usage

Usage command: API cost visibility from local SQLite + X API sync (default). Reads the usage table for estimated costs; fetches actuals from GET /2/usage/tweets by default. Use --local to skip the API and show only local estimates.

watchlist

Watchlist command: manage and check a curated list of X users. Config-driven (config.toml), uses toml_edit for formatting-preserving writes.