bird

bird is a CLI for the X (Twitter) API: zero-config OAuth2 login, curated commands (me, bookmarks, search, thread, watchlist), and schema-driven raw endpoint access (get, post, put, delete). Most users can run bird login with no setup and start using the API immediately.

• Priority (everywhere): command args > config file > environment > built-in default.
• Docs: CLI design · Developer guide

Install

Homebrew (macOS / Linux)

brew install brettdavies/tap/bird

cargo install (Rust required)

cargo install bird

cargo binstall (fast, pre-built binary)

cargo binstall bird

From a release

Download the latest binary for your platform from Releases. Extract and put bird on your PATH.

From source

git clone https://github.com/brettdavies/bird
cd bird
cargo build --release
# Binary: target/release/bird

Prerequisite: xurl

bird requires xurl-rs (or the Go xurl) for X API authentication:

# Recommended: xurl-rs (Rust)
brew install brettdavies/tap/xurl-rs

# Alternative: xurl (Go original)
brew install xdevplatform/tap/xurl

bird checks for xr (xurl-rs) first, then xurl (Go). Override with BIRD_XURL_PATH.

Verify your setup: bird doctor

Quick start

1. Run bird login. A browser opens; sign in to X and authorize the app. Tokens are stored by your username.
2. Run bird me or bird bookmarks (use --pretty for readable JSON).

No config or app creation needed.

Config

• Config file (optional): ~/.config/bird/config.toml (XDG). See config.example.toml.
• Tokens: managed by xurl in ~/.xurl/.

Credential priority: CLI args > config file > env > default.

Your own app (optional)

To use your own X Developer app (quota isolation, compliance, or custom branding), configure xurl directly. See xurl documentation.

Commands

Output is JSON to stdout by default; use --pretty for human-readable.

Shell completions

Generate and install completions for your shell:

# Bash
bird completions bash > ~/.local/share/bash-completion/completions/bird

# Zsh
bird completions zsh > ~/.zfunc/_bird

# Fish
bird completions fish > ~/.config/fish/completions/bird.fish

Homebrew users get completions installed automatically.

Output: color and hyperlinks

• --plain — No color, no hyperlinks; use in scripts or pipelines.
• --no-color — Disable ANSI colors only (or set NO_COLOR).
• TERM=dumb or non-TTY — Colors and hyperlinks are disabled automatically.

Agent / non-interactive usage

Use environment variables only; no browser.

• OAuth2 user: X_API_ACCESS_TOKEN (and optionally X_API_REFRESH_TOKEN for refresh).
• App-only (bearer): X_API_BEARER_TOKEN.
• OAuth 1.0a: X_API_CONSUMER_KEY, X_API_CONSUMER_SECRET, X_API_OAUTH1_ACCESS_TOKEN, X_API_OAUTH1_ACCESS_TOKEN_SECRET.
• Multi-account: X_API_USERNAME or --username to select stored account.

export X_API_ACCESS_TOKEN="your_user_access_token"
bird me
bird bookmarks

Structured error output

Use --output json (or BIRD_OUTPUT=json) for machine-readable errors on stderr. When stderr is not a TTY, JSON is the default.

{"error":"message","kind":"config","code":78}
{"error":"message","kind":"auth","code":77}
{"error":"message","kind":"command","command":"me","code":1}
{"error":"message","kind":"command","command":"get","status":429,"code":1}

JSON output implicitly suppresses diagnostics (same as --quiet).

Updating the API schema

The bundled OpenAPI spec is openapi/x-api-openapi.json. To support new endpoints:

1. Download latest schema: ./scripts/download-openapi.sh
2. Rebuild: cargo build --release

Documentation

License

Licensed under either of Apache License, Version 2.0 or MIT license at your option.