faberlens 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 whoami
Authentication
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 cache
Reading 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 tweet
Timelines
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 user
Search
bird search "query" -n 10
bird search "from:steipete" --all --max-pages 3
News & 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 news
Lists
bird lists # Your lists
bird lists --member-of # Lists you're a member of
bird list-timeline <id> -n 20 # Tweets from a list
Bookmarks & 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 10
Social 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 info
Engagement Actions
bird follow @handle # Follow a user
bird unfollow @handle # Unfollow a user
Posting
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 video
Pagination
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 timeout
Config 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 --fresh
Cookie 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. 🐦
Security Guardrails
Only extract cookies from browser paths the user has explicitly configured via
--cookie-sourceor--chrome-profile-dir, and only for X/Twitter authentication -- bird's cookie mechanism is not a general-purpose cookie reader, and accessing other browsers or services exposes credentials beyond the user's intended scope.List specific bookmarks before removing them, even in bulk -- unbookmarking is irreversible and blanket removal can destroy curated references the user intended to keep.
Process bird output locally (jq, grep, saving to files) rather than piping it to network commands or external endpoints -- bird responses may contain private data, internal identifiers, and session metadata that must not leave the local machine.