bird - Fast X CLI

A fast command-line interface for X/Twitter using cookie authentication and the GraphQL API.

Overview

bird is a CLI tool for tweeting, replying, reading threads, searching, and managing your Twitter/X account — powered by X's internal GraphQL endpoints and your existing browser session.

• Auth: Uses browser cookies (Safari/Chrome/Firefox)
• API: X/Twitter GraphQL API (query IDs auto-refresh)
• Output: Human-readable by default, --json or --plain for scripts

Installation

npm/pnpm/bun (Recommended)

# npm
npm install -g @steipete/bird

# pnpm
pnpm add -g @steipete/bird

# bun
bun add -g @steipete/bird

Homebrew (macOS)

brew install steipete/tap/bird

One-shot (No Install)

# Run without installing
bunx @steipete/bird whoami

Requirements: Node.js ≥ 20

Authentication

Bird uses your existing X.com browser session via cookies.

Browser Options (Auto-Detected)

# Uses Safari (default on macOS)
bird whoami

# Explicit Chrome profile
bird --chrome-profile default whoami

# Firefox
bird --firefox-profile default-release whoami

# Custom profile directory
bird --chrome-profile-dir /path/to/profile whoami

Cookie Setup

Bird reads cookies from your browser. Make sure you're logged into x.com in one of:

• Safari (default on macOS)
• Chrome/Chromium
• Firefox

Environment Variables

# Cookie timeout (ms)
export BIRD_COOKIE_TIMEOUT_MS=300000

# Timeout for requests (ms)
export BIRD_TIMEOUT_MS=30000

# Default quote depth
export BIRD_QUOTE_DEPTH=1

# Disable colors
export NO_COLOR=1

Commands

Tweet

# Post a tweet
bird tweet "Hello from bird CLI!"

# With media
bird tweet "Check this out" --media /path/to/image.jpg

# Quote tweet
bird tweet "My thoughts" --quote https://x.com/user/status/1234567890

Reply

# Reply to a tweet
bird reply https://x.com/user/status/1234567890 "Great point!"

# Deep reply chain
bird reply 1234567890 "Adding to the conversation"

Read

# Read a tweet by ID or URL
bird read 1234567890

# JSON output for scripts
bird read 1234567890 --json

# Full thread
bird thread 1234567890

Search

# Search tweets
bird search "AI tools"

# With count
bird search "AI tools" -n 20

# Since date (YYYY-MM-DD)
bird search "AI tools since:2026-01-01"

# JSON output
bird search "AI tools" --json

Mentions

# Your mentions
bird mentions

# JSON output
bird mentions --json

# Limit results
bird mentions -n 50

Bookmarks

# Get bookmarks
bird bookmarks

# Remove bookmark
bird unbookmark https://x.com/user/status/1234567890

Timeline

# Home timeline ("For You" feed)
bird home

# JSON output
bird home --json

User Tweets

# Tweets from a user
bird user-tweets username

# JSON output
bird user-tweets username --json

Lists

# Your Twitter lists
bird lists

# List timeline
bird list-timeline https://x.com/i/lists/1234567890

Trending/News

# AI-curated news and trending topics
bird news
bird trending

Following/Followers

# Users you follow
bird following

# Your followers
bird followers

# User's followers
bird followers username

# JSON output
bird following --json

Likes

# Your liked tweets
bird likes

Identity

# Check current account
bird whoami

Configuration Files

Config Locations

• Project: .birdrc.json5 (local to project)
• User: ~/.config/bird/config.json5 (global)

Config Options

{
  // Chrome profile name (for cookie extraction)
  chromeProfile: "Default",
  
  // Chrome profile directory (alternative to name)
  chromeProfileDir: "/path/to/profile",
  
  // Firefox profile name
  firefoxProfile: "default-release",
  
  // Cookie extraction timeout (ms)
  cookieTimeoutMs: 300000,
  
  // Request timeout (ms)
  timeoutMs: 30000,
  
  // Max quoted tweet depth (0 = disabled)
  quoteDepth: 1,
}

Usage with Research Scripts

reddit-research Skill

# Set Chrome profile for bird
export BIRD_CHROME_DIR="$HOME/.gemini/antigravity-browser-profile/Default"

# Run research with X search
python3 scripts/last30days.py "AI tools" --sources=x

# Both Reddit + X
python3 scripts/last30days.py "AI tools"

OpenClaw Integration

Bird works seamlessly with OpenClaw skills for agent workflows:

# Bird is auto-detected by research skills
export BIRD_CHROME_DIR="$HOME/.gemini/antigravity-browser-profile/Default"

Scripting

JSON Output

# Get structured data
tweets=$(bird search "AI tools" --json | jq '.[] | {id, text, author}')
echo "$tweets"

Bash Integration

#!/bin/bash
# Search and process tweets

BIRD_DIR="$HOME/.gemini/antigravity-browser-profile/Default"

bird search "$1" -n 10 --json --chrome-profile-dir "$BIRD_DIR" | \
  jq -r '.[] | "\(.author.username): \(.text[:100])"' | \
  while read line; do
    echo "• $line"
  done

Troubleshooting

Missing Cookies

❌ auth_token: not found
❌ ct0: not found

Fix: Log into x.com in your browser and refresh the page.

Safari Cookies Permission

⚠️ Failed to read Safari cookies: EPERM

Fix: Use Chrome or Firefox profile instead:

bird --chrome-profile default whoami

Rate Limiting

Bird respects X's rate limits. If you hit limits:

• Wait before making more requests
• Use --plain for reduced output
• Add delays between requests

Query ID Errors

If you see GraphQL query errors, run:

bird query-ids --refresh

This refreshes cached query IDs.

Alternatives

If bird doesn't work for your use case:

Tool	Auth	Notes
twarc	Twitter API	Academic/research
t	Twitter API	Ruby-based
twitter-cli	Twitter API	Node.js
Nitter	None	Web front-end

License

MIT License - See LICENSE

Author

@steipete - Created and maintained by Peter Steinberger

---

Note: This is a documentation backup repo. The original source is at @steipete/bird on npm.