bird 🐦

Fast X/Twitter CLI using GraphQL + cookie auth.

Install

bash
1# npm/pnpm/bun
2npm install -g @steipete/bird
3
4# Homebrew (macOS, prebuilt binary)
5brew install steipete/tap/bird
6
7# One-shot (no install)
8bunx @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

bash
1bird whoami                    # Show logged-in account
2bird check                     # Show credential sources
3bird query-ids --fresh         # Refresh GraphQL query ID cache

Reading Tweets

bash
1bird read <url-or-id>          # Read a single tweet
2bird <url-or-id>               # Shorthand for read
3bird thread <url-or-id>        # Full conversation thread
4bird replies <url-or-id>       # List replies to a tweet

Timelines

bash
1bird home                      # Home timeline (For You)
2bird home --following          # Following timeline
3bird user-tweets @handle -n 20 # User's profile timeline
4bird mentions                  # Tweets mentioning you
5bird mentions --user @handle   # Mentions of another user

Search

bash
1bird search "query" -n 10
2bird search "from:steipete" --all --max-pages 3

News & Trending

bash
1bird news -n 10                # AI-curated from Explore tabs
2bird news --ai-only            # Filter to AI-curated only
3bird news --sports             # Sports tab
4bird news --with-tweets        # Include related tweets
5bird trending                  # Alias for news

Lists

bash
1bird lists                     # Your lists
2bird lists --member-of         # Lists you're a member of
3bird list-timeline <id> -n 20  # Tweets from a list

Bookmarks & Likes

bash
1bird bookmarks -n 10
2bird bookmarks --folder-id <id>           # Specific folder
3bird bookmarks --include-parent           # Include parent tweet
4bird bookmarks --author-chain             # Author's self-reply chain
5bird bookmarks --full-chain-only          # Full reply chain
6bird unbookmark <url-or-id>
7bird likes -n 10

Social Graph

bash
1bird following -n 20           # Users you follow
2bird followers -n 20           # Users following you
3bird following --user <id>     # Another user's following
4bird about @handle             # Account origin/location info

Engagement Actions

bash
1bird follow @handle            # Follow a user
2bird unfollow @handle          # Unfollow a user

Posting

bash
1bird tweet "hello world"
2bird reply <url-or-id> "nice thread!"
3bird 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

bash
1bird tweet "hi" --media img.png --alt "description"
2bird tweet "pics" --media a.jpg --media b.jpg  # Up to 4 images
3bird tweet "video" --media clip.mp4            # Or 1 video

Pagination

Commands supporting pagination: replies, thread, search, bookmarks, likes, list-timeline, following, followers, user-tweets

bash
1bird bookmarks --all                    # Fetch all pages
2bird bookmarks --max-pages 3            # Limit pages
3bird bookmarks --cursor <cursor>        # Resume from cursor
4bird replies <id> --all --delay 1000    # Delay between pages (ms)

Output Options

bash
1--json          # JSON output
2--json-full     # JSON with raw API response
3--plain         # No emoji, no color (script-friendly)
4--no-emoji      # Disable emoji
5--no-color      # Disable ANSI colors (or set NO_COLOR=1)
6--quote-depth n # Max quoted tweet depth in JSON (default: 1)

Global Options

bash
1--auth-token <token>       # Set auth_token cookie
2--ct0 <token>              # Set ct0 cookie
3--cookie-source <source>   # Cookie source for browser cookies (repeatable)
4--chrome-profile <name>    # Chrome profile name
5--chrome-profile-dir <path> # Chrome/Chromium profile dir or cookie DB path
6--firefox-profile <name>   # Firefox profile
7--timeout <ms>             # Request timeout
8--cookie-timeout <ms>      # Cookie extraction timeout

Config File

~/.config/bird/config.json5 (global) or ./.birdrc.json5 (project):

json5
1{
2  cookieSource: ["chrome"],
3  chromeProfileDir: "/path/to/Arc/Profile",
4  timeoutMs: 20000,
5  quoteDepth: 1,
6}

Environment variables: BIRD_TIMEOUT_MS, BIRD_COOKIE_TIMEOUT_MS, BIRD_QUOTE_DEPTH

Troubleshooting

Query IDs stale (404 errors)

bash
1bird 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. 🐦