- name
- bird
- description
- X/Twitter CLI for reading, searching, posting, and engagement via cookies.
- homepage
- https://bird.fast
- metadata
- {"clawdbot":{"emoji":"🐦","requires":{"bins":["bird"]},"install":[{"id":"brew","kind":"brew","formula":"steipete/tap/bird","bins":["bird"],"label":"Install bird (brew)","os":["darwin"]},{"id":"npm","kind":"node","package":"@steipete/bird","bins":["bird"],"label":"Install bird (npm)"}]}}
bird 🐦
Fast X/Twitter CLI using GraphQL + cookie auth.
Install
# npm/pnpm/bun
npm install -g @steipete/bird
# Homebrew (macOS, prebuilt binary)
brew install steipete/tap/bird
# One-shot (no install)
bunx @steipete/bird whoamiAuthentication
bird uses cookie-based auth.
Use --auth-token / --ct0 to pass cookies directly, or --cookie-source for browser cookies.
Run bird check to see which source is active. For Arc/Brave, use --chrome-profile-dir <path>.
Commands
Account & Auth
bird whoami # Show logged-in account
bird check # Show credential sources
bird query-ids --fresh # Refresh GraphQL query ID cacheReading Tweets
bird read <url-or-id> # Read a single tweet
bird <url-or-id> # Shorthand for read
bird thread <url-or-id> # Full conversation thread
bird replies <url-or-id> # List replies to a tweetTimelines
bird home # Home timeline (For You)
bird home --following # Following timeline
bird user-tweets @handle -n 20 # User's profile timeline
bird mentions # Tweets mentioning you
bird mentions --user @handle # Mentions of another userSearch
bird search "query" -n 10
bird search "from:steipete" --all --max-pages 3News & Trending
bird news -n 10 # AI-curated from Explore tabs
bird news --ai-only # Filter to AI-curated only
bird news --sports # Sports tab
bird news --with-tweets # Include related tweets
bird trending # Alias for newsLists
bird lists # Your lists
bird lists --member-of # Lists you're a member of
bird list-timeline <id> -n 20 # Tweets from a listBookmarks & Likes
bird bookmarks -n 10
bird bookmarks --folder-id <id> # Specific folder
bird bookmarks --include-parent # Include parent tweet
bird bookmarks --author-chain # Author's self-reply chain
bird bookmarks --full-chain-only # Full reply chain
bird unbookmark <url-or-id>
bird likes -n 10Social Graph
bird following -n 20 # Users you follow
bird followers -n 20 # Users following you
bird following --user <id> # Another user's following
bird about @handle # Account origin/location infoEngagement Actions
bird follow @handle # Follow a user
bird unfollow @handle # Unfollow a userPosting
bird tweet "hello world"
bird reply <url-or-id> "nice thread!"
bird tweet "check this out" --media image.png --alt "description"⚠️ Posting risks: Posting is more likely to be rate limited; if blocked, use the browser tool instead.
Media Uploads
bird tweet "hi" --media img.png --alt "description"
bird tweet "pics" --media a.jpg --media b.jpg # Up to 4 images
bird tweet "video" --media clip.mp4 # Or 1 videoPagination
Commands supporting pagination: replies, thread, search, bookmarks, likes, list-timeline, following, followers, user-tweets
bird bookmarks --all # Fetch all pages
bird bookmarks --max-pages 3 # Limit pages
bird bookmarks --cursor <cursor> # Resume from cursor
bird replies <id> --all --delay 1000 # Delay between pages (ms)Output Options
--json # JSON output
--json-full # JSON with raw API response
--plain # No emoji, no color (script-friendly)
--no-emoji # Disable emoji
--no-color # Disable ANSI colors (or set NO_COLOR=1)
--quote-depth n # Max quoted tweet depth in JSON (default: 1)Global Options
--auth-token <token> # Set auth_token cookie
--ct0 <token> # Set ct0 cookie
--cookie-source <source> # Cookie source for browser cookies (repeatable)
--chrome-profile <name> # Chrome profile name
--chrome-profile-dir <path> # Chrome/Chromium profile dir or cookie DB path
--firefox-profile <name> # Firefox profile
--timeout <ms> # Request timeout
--cookie-timeout <ms> # Cookie extraction timeoutConfig File
~/.config/bird/config.json5 (global) or ./.birdrc.json5 (project):
{
cookieSource: ["chrome"],
chromeProfileDir: "/path/to/Arc/Profile",
timeoutMs: 20000,
quoteDepth: 1
}Environment variables: BIRD_TIMEOUT_MS, BIRD_COOKIE_TIMEOUT_MS, BIRD_QUOTE_DEPTH
Troubleshooting
Query IDs stale (404 errors)
bird query-ids --freshCookie extraction fails
- Check browser is logged into X
- Try different
--cookie-source - For Arc/Brave: use
--chrome-profile-dir
TL;DR: Read/search/engage with CLI. Post carefully or use browser. 🐦