# bird-premium 🐦💰

X/Twitter CLI using the **official paid API v2**. A fork of [steipete/bird](https://github.com/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

```bash
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:

```bash
export X_BEARER_TOKEN="your-bearer-token"
```

### OAuth 1.0a (User Context)

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

```bash
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](https://developer.x.com/).

## Commands

### Search

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

### Read Tweet

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

### User Profile

```bash
bird user elonmusk
bird user @anthropic --json
```

### User Tweets

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

### List Timeline

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

### Followers / Following

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

### Mentions (OAuth 1.0a)

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

### Likes (OAuth 1.0a)

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

### Who Am I (OAuth 1.0a)

```bash
bird whoami
bird whoami --json
```

### Check Credentials

```bash
bird check
```

## JSON Output

Add `--json` to any command:

```bash
bird user elonmusk --json
```

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

## Pagination

Use `--cursor` for pagination:

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

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

## Library Usage

```typescript
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