bird is a fast X CLI for tweeting, replying, and reading. It uses either GraphQL cookies or the Sweetistics API.

npm install -g @steipete/bird
# or
pnpm add -g @steipete/bird

# Show the logged-in account
bird whoami

# Read a tweet (URL or ID)
bird read https://x.com/user/status/1234567890123456789
bird 1234567890123456789 --json

# Thread + replies
bird thread https://x.com/user/status/1234567890123456789
bird replies 1234567890123456789

# Search + mentions
bird search "from:steipete" -n 5
bird mentions -n 5

• bird tweet "<text>" — post a new tweet.
• bird reply <tweet-id-or-url> "<text>" — reply to a tweet using its ID or URL.
• bird read <tweet-id-or-url> [--json] — fetch tweet content as text or JSON.
• bird <tweet-id-or-url> [--json] — shorthand for read when only a URL or ID is provided.
• bird replies <tweet-id-or-url> [--json] — list replies to a tweet.
• bird thread <tweet-id-or-url> [--json] — show the full conversation thread.
• bird search "<query>" [-n count] [--json] — search for tweets matching a query.
• bird mentions [-n count] [--json] — find tweets mentioning @clawdbot.
• bird whoami — print which Twitter account your cookies belong to.
• bird check — show which credentials are available and where they were sourced from.

• --engine graphql (default) — use Twitter/X GraphQL with cookies (Chrome/Firefox/env/flags).
• --engine sweetistics — use Sweetistics API key (no browser cookies needed).
• --engine auto — Sweetistics if a key is available, otherwise GraphQL.

Global options:

• --timeout <ms>: abort requests after the given timeout (milliseconds).

bird resolves credentials in this order:

1. CLI flags: --auth-token, --ct0
2. Environment variables: AUTH_TOKEN, CT0 (fallback: TWITTER_AUTH_TOKEN, TWITTER_CT0)
3. Browser cookies (macOS): Firefox or Chrome profiles

Browser cookie sources:

• Firefox (default): ~/Library/Application Support/Firefox/Profiles/<profile>/cookies.sqlite
• Chrome: ~/Library/Application Support/Google/Chrome/<Profile>/Cookies

Config precedence: CLI flags > env vars > project config > global config.

• Global: ~/.config/bird/config.json5
• Project: ./.birdrc.json5

Example ~/.config/bird/config.json5:

{
  engine: "graphql",
  firefoxProfile: "default-release",
  sweetisticsApiKey: "sweet-...",
  allowFirefox: true,
  allowChrome: false,
  timeoutMs: 20000
}

Environment shortcuts:

• SWEETISTICS_API_KEY, SWEETISTICS_BASE_URL
• BIRD_ENGINE, BIRD_TIMEOUT_MS

• --json prints raw tweet objects for read/replies/thread/search/mentions.
• read returns full text for Notes and Articles when present.

• Attach media with --media (repeatable) and optional --alt per item.
• Up to 4 images, or 1 video (no mixing). Supported: jpg, jpeg, png, webp, gif, mp4, mov.

Example:

bird --engine sweetistics tweet "hi" --media img.png --alt "desc"

cd ~/Projects/bird
pnpm install
pnpm run build       # dist/ + bun binary
pnpm run build:dist  # dist/ only
pnpm run build:binary

pnpm run dev tweet "Test"
pnpm test
pnpm run lint

• GraphQL uses internal X endpoints and can be rate limited (429).
• Query IDs rotate; refresh them with pnpm run graphql:update.