{"id":47600664,"url":"https://github.com/brettdavies/bird","last_synced_at":"2026-04-01T18:50:11.733Z","repository":{"id":345122635,"uuid":"1153998094","full_name":"brettdavies/bird","owner":"brettdavies","description":"Rust CLI for the X (Twitter) API — entity store, watchlist, thread reconstruction, and usage tracking on top of xurl.","archived":false,"fork":false,"pushed_at":"2026-03-25T18:33:01.000Z","size":795,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-26T18:25:58.175Z","etag":null,"topics":["api-client","caching","cli","rust","sqlite","twitter","x-api"],"latest_commit_sha":null,"homepage":"https://crates.io/crates/bird","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/brettdavies.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-09T22:48:25.000Z","updated_at":"2026-03-25T18:27:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/brettdavies/bird","commit_stats":null,"previous_names":["brettdavies/bird"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/brettdavies/bird","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettdavies%2Fbird","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettdavies%2Fbird/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettdavies%2Fbird/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettdavies%2Fbird/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/brettdavies","download_url":"https://codeload.github.com/brettdavies/bird/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/brettdavies%2Fbird/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","caching","cli","rust","sqlite","twitter","x-api"],"created_at":"2026-04-01T18:50:10.982Z","updated_at":"2026-04-01T18:50:11.724Z","avatar_url":"https://github.com/brettdavies.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bird\n\n**bird** is a Rust CLI for the X (Twitter) API, built on [xurl](https://github.com/xdevplatform/xurl) for\nauthentication and transport. It adds a local entity store, watchlist monitoring, usage tracking, thread\nreconstruction, and structured error output for agents.\n\n## Why bird?\n\nxurl already provides authentication, curated commands, and raw API access. bird extends xurl with capabilities it\ndoesn't have:\n\n- **Entity store** — Local SQLite cache with per-endpoint TTL. Reduces API calls, enables offline access, and supports\n  `--refresh`, `--no-cache`, and `--cache-only` modes.\n- **Thread reconstruction** — Rebuilds full conversation threads from a single tweet ID.\n- **Watchlist** — Monitor a list of users for recent activity without manual searches.\n- **Usage tracking** — Local API usage history with cost estimation; `--sync` to refresh from the X API.\n- **Structured errors** — Machine-readable JSON errors on stderr for agent and CI integration.\n- **Self-diagnostics** — `bird doctor` reports xurl status, auth state, command availability, and store health in one\n  place.\n\nbird delegates all authentication and HTTP transport to xurl at runtime.\n\n---\n\n## Install\n\n### Homebrew (macOS / Linux)\n\n```bash\nbrew tap brettdavies/tap\nbrew install bird\n```\n\n### crates.io\n\n```bash\n# From source (requires Rust toolchain)\ncargo install bird\n\n# Pre-built binary (fast, no compiler needed)\ncargo binstall bird\n```\n\n### From a release\n\nDownload the latest binary for your platform from [Releases](https://github.com/brettdavies/bird/releases). Extract\nand place `bird` on your `PATH`.\n\n### From source\n\n```bash\ngit clone https://github.com/brettdavies/bird\ncd bird\ncargo build --release\n# Binary: target/release/bird\n```\n\n### Prerequisite: xurl\n\nbird requires [xurl-rs](https://github.com/brettdavies/xurl-rs) (or the Go\n[xurl](https://github.com/xdevplatform/xurl)) for X API authentication:\n\n```bash\n# Recommended: xurl-rs (Rust)\nbrew tap brettdavies/tap\nbrew install xurl-rs\n\n# Alternative: xurl (Go original)\nbrew tap xdevplatform/tap\nbrew install xurl\n```\n\nbird checks for `xr` (xurl-rs) first, then `xurl` (Go). Override with `BIRD_XURL_PATH`.\n\nVerify your setup: `bird doctor`\n\n---\n\n## Quick start\n\n```bash\nbird login           # Opens browser, sign in, done\nbird me --pretty     # Current user profile\nbird bookmarks       # List bookmarks (paginated)\nbird search \"rust lang\" --sort likes --min-likes 100\nbird tweet \"Hello from bird\"\n```\n\nNo config or app creation needed.\n\n---\n\n## Commands\n\n### Read\n\n| Command                  | Description                                                        |\n| ------------------------ | ------------------------------------------------------------------ |\n| `bird me`                | Current user (`GET /2/users/me`)                                   |\n| `bird bookmarks`         | List bookmarks (paginated, max 100 per page)                       |\n| `bird profile \u003cuser\u003e`    | Look up a user by username                                         |\n| `bird search \u003cquery\u003e`    | Search recent tweets; `--sort likes`, `--min-likes N`, `--pages N` |\n| `bird thread \u003ctweet_id\u003e` | Reconstruct a conversation thread                                  |\n\n### Write\n\n| Command                   | Description                |\n| ------------------------- | -------------------------- |\n| `bird tweet \u003ctext\u003e`       | Post a tweet               |\n| `bird reply \u003cid\u003e \u003ctext\u003e`  | Reply to a tweet           |\n| `bird like \u003cid\u003e`          | Like a tweet               |\n| `bird unlike \u003cid\u003e`        | Unlike a tweet             |\n| `bird repost \u003cid\u003e`        | Repost (retweet) a tweet   |\n| `bird unrepost \u003cid\u003e`      | Undo a repost              |\n| `bird follow \u003cuser\u003e`      | Follow a user              |\n| `bird unfollow \u003cuser\u003e`    | Unfollow a user            |\n| `bird dm \u003cuser\u003e \u003ctext\u003e`   | Send a direct message      |\n| `bird block \u003cuser\u003e`       | Block a user               |\n| `bird unblock \u003cuser\u003e`     | Unblock a user             |\n| `bird mute \u003cuser\u003e`        | Mute a user                |\n| `bird unmute \u003cuser\u003e`      | Unmute a user              |\n\n### Monitoring\n\n| Command                        | Description                             |\n| ------------------------------ | --------------------------------------- |\n| `bird watchlist check`         | Check recent activity for watched users |\n| `bird watchlist add \u003cuser\u003e`    | Add a user to the watchlist             |\n| `bird watchlist remove \u003cuser\u003e` | Remove a user from the watchlist        |\n| `bird watchlist list`          | Show the current watchlist              |\n| `bird usage`                   | View local API usage and cost estimates |\n| `bird usage --sync`            | Refresh usage data from the X API       |\n\n### Raw API access\n\n| Command              | Description                                             |\n| -------------------- | ------------------------------------------------------- |\n| `bird get \u003cpath\u003e`    | `GET` request; supports path templates with `-p id=123` |\n| `bird post \u003cpath\u003e`   | `POST` request; optional `--body '{\"text\":\"...\"}'`      |\n| `bird put \u003cpath\u003e`    | `PUT` request                                           |\n| `bird delete \u003cpath\u003e` | `DELETE` request                                        |\n\n### System\n\n| Command                       | Description                                                        |\n| ----------------------------- | ------------------------------------------------------------------ |\n| `bird login`                  | Sign in via browser (delegates to xurl)                            |\n| `bird doctor`                 | Diagnostics: xurl status, auth, commands, store health             |\n| `bird doctor \u003ccmd\u003e`           | Scoped diagnostics for a single command                            |\n| `bird cache stats`            | Entity store status                                                |\n| `bird cache clear`            | Delete all cached entities                                         |\n| `bird completions \u003cshell\u003e`    | Generate shell completions (bash, zsh, fish, powershell, elvish)   |\n\n---\n\n## Entity store\n\nbird maintains a local SQLite entity store that caches API responses with per-endpoint TTL. This reduces redundant API\ncalls and provides offline access to previously fetched data.\n\n```bash\nbird search \"rust\" --refresh     # Bypass store, fetch fresh, update store\nbird search \"rust\" --no-cache    # Skip store entirely (no read, no write)\nbird search \"rust\" --cache-only  # Serve from store only, no API requests\nbird cache stats --pretty        # View store status\nbird cache clear                 # Wipe the store\n```\n\n---\n\n## Output and formatting\n\nAll commands emit JSON to stdout by default. Use `--pretty` for human-readable output.\n\n```bash\nbird me --pretty         # Formatted, colored output\nbird me --plain          # No color, no hyperlinks (script-friendly)\nbird me --no-color       # Disable ANSI colors only (or set NO_COLOR)\nbird me --output json    # Force JSON error output on stderr\nbird me -q               # Suppress informational stderr messages\n```\n\nColors and hyperlinks are disabled automatically when stdout is not a TTY or `TERM=dumb`.\n\n---\n\n## Agent and non-interactive usage\n\nAuthentication is handled entirely by xurl. For headless/CI environments where a browser is not available, configure\nauth tokens through xurl's environment variables — see [xurl documentation](https://github.com/xdevplatform/xurl).\n\nbird reads one environment variable: `X_API_USERNAME` (or `--username`) to select which stored account xurl should use.\n\n### Structured error output\n\nUse `--output json` (or `BIRD_OUTPUT=json`) for machine-readable errors on stderr. When stderr is not a TTY, JSON is\nthe default.\n\n```json\n{\"error\":\"message\",\"kind\":\"config\",\"code\":78}\n{\"error\":\"message\",\"kind\":\"auth\",\"code\":77}\n{\"error\":\"message\",\"kind\":\"command\",\"command\":\"me\",\"code\":1}\n{\"error\":\"message\",\"kind\":\"command\",\"command\":\"get\",\"status\":429,\"code\":1}\n```\n\n| Field     | Type   | Description                               |\n| --------- | ------ | ----------------------------------------- |\n| `error`   | string | Error message                             |\n| `kind`    | string | `config`, `auth`, or `command`            |\n| `code`    | number | Exit code (78, 77, or 1)                  |\n| `command` | string | Command name (only for `kind: \"command\"`) |\n| `status`  | number | HTTP status (only for API errors)         |\n\n---\n\n## Config\n\nbird's own config is minimal — just `username` and `watchlist`:\n\n- **Config file (optional):** `~/.config/bird/config.toml`\n- **Entity store:** `~/.config/bird/bird.db` (SQLite)\n\nUsername priority: `--username` flag \u003e config file \u003e `X_API_USERNAME` env var.\n\nAuthentication and token storage are handled entirely by xurl. To use your own X Developer app, configure it through\nxurl — see [xurl documentation](https://github.com/xdevplatform/xurl).\n\n---\n\n## Shell completions\n\nGenerate and install completions for your shell:\n\n```bash\n# Bash\nbird completions bash \u003e ~/.local/share/bash-completion/completions/bird\n\n# Zsh\nbird completions zsh \u003e ~/.zfunc/_bird\n\n# Fish\nbird completions fish \u003e ~/.config/fish/completions/bird.fish\n```\n\nHomebrew users get completions installed automatically.\n\n---\n\n## Documentation\n\n| Doc                                           | Purpose                                                              |\n| --------------------------------------------- | -------------------------------------------------------------------- |\n| [docs/CLI_DESIGN.md](docs/CLI_DESIGN.md)      | Auth requirements, doctor, and error design                          |\n| [docs/DEVELOPER.md](docs/DEVELOPER.md)        | Build from source, architecture, project layout                      |\n| [RELEASING.md](RELEASING.md)                  | Release process and distribution channels                            |\n| [CHANGELOG.md](CHANGELOG.md)                  | Version history (generated by [git-cliff](https://git-cliff.org))    |\n\n---\n\n## License\n\nLicensed under either of [Apache License, Version 2.0](LICENSE-APACHE) or [MIT license](LICENSE-MIT) at your option.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrettdavies%2Fbird","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrettdavies%2Fbird","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrettdavies%2Fbird/lists"}