bird CLI

A command-line interface for interacting with X/Twitter directly from the terminal, using your existing browser session for authentication.

Overview

bird is a TypeScript-based CLI that provides terminal access to X/Twitter functionality without requiring API keys or OAuth flows. It extracts authentication cookies from your web browser (Safari, Chrome, or Firefox) and uses Twitter's internal GraphQL API with automatic query ID management.

Key Features:

• Zero-configuration authentication via browser cookies
• Full tweet lifecycle: post, reply, read, search
• Media uploads (images, GIFs, videos) with alt text
• Multiple output formats (human-readable, JSON, plain)
• Automatic GraphQL query ID refresh and REST API fallback

When to Use

• Posting tweets or replies from scripts or automation
• Reading and analyzing tweet threads programmatically
• Searching for mentions or specific content
• Building social media automation workflows
• Testing Twitter integrations from the command line
• Extracting tweet content for analysis

Prerequisites

• Node.js >= 22 (for npm/pnpm/bun installation) OR Homebrew (for standalone binary)
• Browser login: Must be logged into x.com in Safari, Chrome, or Firefox

Installation

# npm
npm install -g @steipete/bird

# pnpm
pnpm add -g @steipete/bird

# bun
bun add -g @steipete/bird

# Homebrew (macOS - standalone binary, no Node.js required)
brew install steipete/tap/bird

One-shot execution without installation:

bunx @steipete/bird whoami
npx @steipete/bird whoami

Authentication

bird resolves credentials using a three-tier priority chain:

Priority	Source	Configuration
1 (highest)	CLI flags	--auth-token, --ct0
2	Environment variables	AUTH_TOKEN, CT0 (or TWITTER_AUTH_TOKEN, TWITTER_CT0)
3 (lowest)	Browser cookies	Auto-extracted from Safari, Chrome, or Firefox

Browser cookie extraction (default behavior):

• Requires being logged into x.com in your browser
• Default order: Safari → Chrome → Firefox
• Customize with --cookie-source flag or config file

Verify authentication:

bird whoami    # Shows authenticated user
bird check     # Shows credential source

Quick Start

# Post a tweet
bird tweet "Hello from the terminal!"

# Read a tweet
bird read https://x.com/user/status/1234567890123456789

# Reply to a tweet
bird reply 1234567890123456789 "Great point!"

# Search tweets
bird search "from:elonmusk" -n 20

# View your mentions
bird mentions

Command Reference

Writing Commands

tweet

Post a new tweet with optional media attachments.

bird tweet "<text>" [options]

Options:

• --media <path> - Attach media file (repeatable, up to 4 images/GIFs or 1 video)
• --alt <text> - Alt text for corresponding --media (repeatable)

Examples:

bird tweet "Check this out!"
bird tweet "Photo gallery" --media img1.jpg --alt "First photo" --media img2.jpg
bird tweet "Demo video" --media demo.mp4

reply

Reply to an existing tweet.

bird reply <tweet-id-or-url> "<text>" [options]

Examples:

bird reply 1234567890123456789 "I agree!"
bird reply https://x.com/user/status/1234567890123456789 "Great thread!"
bird reply 1234567890123456789 "Here's a screenshot" --media screenshot.png --alt "Screenshot"

Reading Commands

read

Fetch a single tweet's content. Handles standard tweets, Notes (long-form), and Articles.

bird read <tweet-id-or-url>

# Shorthand: just provide the ID or URL
bird 1234567890123456789
bird https://x.com/user/status/1234567890123456789

replies

List all replies to a tweet.

bird replies <tweet-id-or-url>

thread

Show a full conversation thread.

bird thread <tweet-id-or-url>

Search Commands

search

Search for tweets matching a query.

bird search "<query>" [-n <count>]

Options:

• -n, --count <number> - Number of results (default: 10)

Examples:

bird search "claude ai" -n 20
bird search "from:anthropic"
bird search "@username"

mentions

Find mentions of a user.

bird mentions [-u <handle>] [-n <count>]

Options:

• -u, --user <handle> - User handle (defaults to authenticated user)
• -n, --count <number> - Number of results (default: 10)

bookmarks

List bookmarked tweets.

bird bookmarks [-n <count>]

Options:

• -n, --count <number> - Number of results (default: 20)

Utility Commands

whoami

Display authenticated user information.

bird whoami

check

Verify credential availability and show their source.

bird check

query-ids

Inspect or refresh the GraphQL query ID cache.

bird query-ids [--fresh] [--json]

Options:

• --fresh - Force refresh by scraping X.com web client bundles
• --json - Output as JSON

help

Show help for a command.

bird help [command]

Global Options

Option	Description
--auth-token <token>	Twitter auth_token cookie
--ct0 <token>	Twitter ct0 cookie
--cookie-source <source>	Browser priority (repeatable: safari, chrome, firefox)
--chrome-profile <name>	Chrome profile name
--firefox-profile <name>	Firefox profile name
--timeout <ms>	Request timeout in milliseconds
--plain	Stable output: disables emoji and color
--no-emoji	Disable emoji in output
--no-color	Disable ANSI colors
--json	Output as JSON (command-specific)

Media Attachments

Supported Formats

Type	Extensions	Limit
Images	.jpg, .jpeg, .png, .webp	Up to 4
GIFs	.gif	Up to 4
Videos	.mp4, .m4v, .mov	1 only

Note: Cannot mix videos with images/GIFs.

Alt Text

Specify alt text for accessibility:

bird tweet "Three photos" \
  --media photo1.jpg --alt "Beach sunset" \
  --media photo2.jpg --alt "Mountain view" \
  --media photo3.jpg --alt "City skyline"

Output Formats

Format	Flag	Use Case
Human-readable	(default)	Interactive terminal use
Plain	--plain	Scripting (no emoji/color)
JSON	--json	Programmatic parsing

Example:

# Parse tweet data in a script
bird read 1234567890123456789 --json | jq '.text'

Configuration Files

Optional JSON5 configuration files:

Location	Scope
~/.config/bird/config.json5	Global (all projects)
./.birdrc.json5	Project-specific

Example config:

{
  cookieSource: ["firefox", "safari"],
  firefoxProfile: "default-release",
  timeoutMs: 20000
}

Examples

Automation Workflow

#!/bin/bash
# Post a daily update
DATE=$(date +"%Y-%m-%d")
bird tweet "Daily standup for $DATE: All systems operational."

Thread Analysis

# Get all replies to a viral tweet
bird replies https://x.com/user/status/1234567890123456789 --json | \
  jq '.[] | .text'

Mention Monitoring

# Check recent mentions
bird mentions -n 50 --json | jq '.[] | {user: .user.screen_name, text: .text}'

Multi-Image Post

bird tweet "Product launch gallery" \
  --media hero.png --alt "Product hero shot" \
  --media feature1.png --alt "Feature overview" \
  --media feature2.png --alt "Technical specs" \
  --media pricing.png --alt "Pricing table"

Best Practices

• Use --json for scripting: Always use --json output when parsing results programmatically
• Use --plain in CI/CD: Avoids emoji/color issues in log files
• Refresh query IDs proactively: Run bird query-ids --fresh if you haven't used bird in a while
• Set up environment variables for automation: Use AUTH_TOKEN and CT0 env vars instead of browser cookies for scripts
• Add alt text for accessibility: Always include --alt when attaching images
• Check auth first: Run bird whoami before complex operations to verify credentials
• Handle rate limits: Twitter may throttle requests; add delays in automation scripts

Troubleshooting

"No auth token found"

• Ensure you're logged into x.com in Safari, Chrome, or Firefox
• Try specifying the browser: bird whoami --cookie-source safari
• Use environment variables: export AUTH_TOKEN=... CT0=...

GraphQL 404 errors

Query IDs may be stale. Refresh the cache:

bird query-ids --fresh

Error 226 (automation detected)

bird automatically falls back to the REST API. If it persists, wait a few minutes and retry.

Wrong account detected

Multiple browser profiles may have different sessions:

bird whoami --cookie-source chrome --chrome-profile "Profile 1"

Exit Codes

Code	Meaning
0	Success
1	Runtime error (network, auth, API)
2	Invalid usage (unknown command, bad arguments)

Technical Notes

• Uses Twitter's private GraphQL API endpoints
• Query IDs are cached locally (~/.config/bird/query-ids-cache.json) with 24-hour TTL
• Automatic query ID refresh on 404 errors
• REST API fallback (statuses/update.json) for error 226
• Subject to breakage if Twitter changes their internal API

Resources

• bird.fast - Official website
• GitHub Repository - Source code and issues
• Changelog - Version history