bird-premium 🐦💰

X/Twitter CLI using the official paid API v2. A fork of steipete/bird that uses the documented API instead of undocumented GraphQL endpoints.

Features

• 🔍 Search recent tweets (last 7 days)
• 📖 Read individual tweets by ID or URL
• 👤 User profiles with follower/following counts
• 📜 User tweets timeline
• 📋 List timeline — get tweets from any public list
• 👥 Followers/Following lists
• 💬 Mentions (with OAuth 1.0a)
• ❤️ Likes (with OAuth 1.0a)
• 📄 JSON output for scripting

Install

npm install -g @dannote/bird-premium
# or
pnpm add -g @dannote/bird-premium
# or
bun add -g @dannote/bird-premium

Authentication

Bearer Token (App-Only)

For read-only access to public data:

export X_BEARER_TOKEN="your-bearer-token"

OAuth 1.0a (User Context)

For user-specific data (mentions, likes) and write operations:

export X_API_KEY="your-api-key"
export X_API_SECRET="your-api-secret"
export X_ACCESS_TOKEN="your-access-token"
export X_ACCESS_TOKEN_SECRET="your-access-token-secret"

Get credentials from the X Developer Portal.

Commands

Search

bird search "Claude AI" -n 10
bird search "from:elonmusk" --json

Read Tweet

bird read 1585841080431321088
bird read https://x.com/elonmusk/status/1585841080431321088 --json

User Profile

bird user elonmusk
bird user @anthropic --json

User Tweets

bird user-tweets elonmusk -n 20
bird user-tweets @anthropic --no-retweets --json

List Timeline

bird list-timeline 1894700501725229467 -n 50
bird list-timeline https://x.com/i/lists/1894700501725229467 --json

Followers / Following

bird followers elonmusk -n 100
bird following @anthropic --json

Mentions (OAuth 1.0a)

bird mentions -n 10
bird mentions @username --json

Likes (OAuth 1.0a)

bird likes -n 20
bird likes @username --json

Who Am I (OAuth 1.0a)

bird whoami
bird whoami --json

Check Credentials

bird check

JSON Output

Add --json to any command:

bird user elonmusk --json

{
  "id": "44196397",
  "username": "elonmusk",
  "name": "Elon Musk",
  "followersCount": 232696510,
  "followingCount": 1273,
  "tweetCount": 94848,
  "verified": true
}

Pagination

Use --cursor for pagination:

bird search "AI" -n 10
# Output includes: Next page: bird search "AI" --cursor b26v89c19zqg8o3...

bird search "AI" -n 10 --cursor b26v89c19zqg8o3...

Library Usage

import { XApiV2Client } from '@dannote/bird-premium';

const client = new XApiV2Client({ 
  bearerToken: process.env.X_BEARER_TOKEN!,
  // Optional OAuth 1.0a for user context
  apiKey: process.env.X_API_KEY,
  apiSecret: process.env.X_API_SECRET,
  accessToken: process.env.X_ACCESS_TOKEN,
  accessTokenSecret: process.env.X_ACCESS_TOKEN_SECRET,
});

// Search tweets
const results = await client.searchRecentTweets('Claude AI', { maxResults: 10 });

// Get list tweets
const listTweets = await client.getListTweets('1894700501725229467', { maxResults: 50 });

// Get user
const user = await client.getUserByUsername('elonmusk');

API Capabilities

| Feature | Bearer Token | OAuth 1.0a | |---------|-------------|------------| | Search | ✅ | ✅ | | Read tweets | ✅ | ✅ | | User profiles | ✅ | ✅ | | User tweets | ✅ | ✅ | | List timeline | ✅ | ✅ | | Followers/Following | ✅ | ✅ | | Mentions | ❌ | ✅ | | Likes | ❌ | ✅ | | Who am I | ❌ | ✅ | | Tweet/Reply* | ❌ | ✅ | | Like/Retweet* | ❌ | ✅ | | Follow/Unfollow* | ❌ | ✅ |

*Write operations require app permissions enabled in Developer Portal.

Why "Premium"?

This CLI uses the official X API v2 which requires a paid developer account. Unlike the original bird which uses undocumented internal GraphQL endpoints with cookie auth, this version:

• ✅ Uses documented, stable API endpoints
• ✅ Won't break when X rotates query IDs
• ✅ Respects rate limits properly
• ✅ Supports official OAuth authentication
• 💰 Requires X API access ($100+/month for Basic tier)

License

MIT