Bird

https://github.com/steipete/bird
Admin
Bird is a fast command-line interface (CLI) for tweeting, replying, and reading on X/Twitter using...
Tokens:9,915
Snippets:71
Trust Score:10
Update:9 months ago
Show doc for...
Tokens:
Raw
### Bird CLI Quickstart Examples

Source: https://github.com/steipete/bird/blob/main/README.md

Common usage examples for the Bird CLI, including checking the logged-in account, getting command help, reading tweets, retrieving threads and replies, searching, managing mentions, bookmarks, likes, following, and followers. It also shows how to refresh the GraphQL query IDs cache.

```bash
# Show the logged-in account
bird whoami

# Discover command help
bird help 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 mentions --user @steipete -n 5

# Bookmarks
bird bookmarks -n 5
bird bookmarks --folder-id 123456789123456789 -n 5 # https://x.com/i/bookmarks/<folder-id>

# Likes
bird likes -n 5

# Following (who you follow)
bird following -n 20
bird following --user 12345678 -n 10  # by user ID

# Followers (who follows you)
bird followers -n 20
bird followers --user 12345678 -n 10  # by user ID

# Refresh GraphQL query IDs cache (no rebuild)
bird query-ids --fresh
```

--------------------------------

### Basic bird.fast CLI usage examples

Source: https://github.com/steipete/bird/blob/main/docs/index.html

Demonstrates basic usage of the bird.fast CLI, including installing the tool and executing simple commands like checking the current user and posting a tweet.

```shell
npm install -g @steipete/bird

bird whoami
bird tweet "hi from bird.fast"
```

--------------------------------

### Configuration Example (JSON5)

Source: https://github.com/steipete/bird/blob/main/README.md

An example of the `bird` CLI configuration file in JSON5 format. This file allows customization of settings such as cookie source order, Firefox profile, and various timeouts. It demonstrates how to specify preferences for extracting browser cookies and setting operational timeouts.

```json5
{
  // Cookie source order for browser extraction (string or array)
  cookieSource: ["firefox", "safari"],
  firefoxProfile: "default-release",
  cookieTimeoutMs: 30000,
  timeoutMs: 20000,
  quoteDepth: 1
}
```

--------------------------------

### Install Bird CLI

Source: https://github.com/steipete/bird/blob/main/README.md

Instructions for installing the Bird CLI globally using npm, pnpm, or bun. It also includes a one-shot execution command using bunx and Homebrew installation for macOS.

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

# one-shot (no install)
bunx @steipete/bird whoami
```

```bash
brew install steipete/tap/bird
```

--------------------------------

### Media Upload Example (Bash)

Source: https://github.com/steipete/bird/blob/main/README.md

Example command for uploading media along with a tweet using the `bird` CLI. It shows how to attach images or videos using the `--media` flag and provide alternative text descriptions with `--alt`. This command demonstrates the basic syntax for including media in posts.

```bash
bird tweet "hi" --media img.png --alt "desc"
```

--------------------------------

### Install bird.fast CLI using Homebrew (macOS)

Source: https://github.com/steipete/bird/blob/main/docs/index.html

Install the bird.fast CLI on macOS using Homebrew. This command installs a prebuilt Bun binary for the tool.

```shell
brew install steipete/tap/bird
```

--------------------------------

### Install bird.fast CLI using npm, pnpm, or bun

Source: https://github.com/steipete/bird/blob/main/docs/index.html

Install the bird.fast CLI globally using your preferred Node.js package manager. This command requires Node.js version 20 or higher.

```shell
npm install -g @steipete/bird
pnpm add -g @steipete/bird
bun add -g @steipete/bird
```

--------------------------------

### Post a Tweet via CLI

Source: https://context7.com/steipete/bird/llms.txt

This is a placeholder for a CLI command example to post a tweet. The actual command syntax would be provided here.

```bash
# Example command structure:
# bird tweet "Your tweet content here" --credentials <path_to_credentials>

```

--------------------------------

### Run bird.fast commands without installation using bunx

Source: https://github.com/steipete/bird/blob/main/docs/index.html

Execute bird.fast commands directly without a global installation using `bunx`. This is useful for trying out the tool or running single commands.

```shell
bunx @steipete/bird whoami
```

--------------------------------

### Development Commands (Bash)

Source: https://github.com/steipete/bird/blob/main/README.md

Common commands for developing the `bird` CLI project. This includes installing dependencies, building the project in various configurations (distribution files, binary), running the development server, and executing tests and linting. These commands are essential for contributing to or modifying the project.

```bash
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 run dev -- --plain check
pnpm test
pnpm run lint
```

--------------------------------

### Use Bird as a TypeScript Library

Source: https://github.com/steipete/bird/blob/main/README.md

Example of how to use the Bird CLI functionality as a library in TypeScript. It demonstrates importing the TwitterClient and resolveCredentials, resolving user credentials, and making a search request.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({ cookies });
const result = await client.search('from:steipete', 50);
```

--------------------------------

### Post a tweet using bird.fast CLI

Source: https://github.com/steipete/bird/blob/main/docs/index.html

Example of how to post a tweet using the `bird tweet` command. The tweet content is provided as a string argument.

```shell
bird tweet "ship it"
```

--------------------------------

### Post a Simple Tweet (TypeScript)

Source: https://context7.com/steipete/bird/llms.txt

This example shows how to post a basic text tweet using the TwitterClient. It first resolves credentials and initializes the client, then calls the `tweet` method with the desired text. The result indicates success or failure, providing the tweet ID on success or an error message.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({ cookies });

// Post a simple text tweet
const result = await client.tweet('Hello from bird! 🐦');

if (result.success) {
  console.log(`Tweet posted: https://x.com/i/status/${result.tweetId}`);
} else {
  console.error(`Failed to post tweet: ${result.error}`);
}

```

--------------------------------

### Get Tweet Thread Conversation using Twitter API

Source: https://context7.com/steipete/bird/llms.txt

Retrieves all tweets that form a conversation thread starting from a given tweet ID. It requires Twitter credentials and returns an array of tweets in the thread.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({ cookies });

const tweetId = '1234567890123456789';
const result = await client.getThread(tweetId);

if (result.success && result.tweets) {
  console.log(`Thread has ${result.tweets.length} tweets:\n`);

  for (const tweet of result.tweets) {
    console.log(`@${tweet.author.username}: ${tweet.text}`);
    if (tweet.inReplyToStatusId) {
      console.log(`  ↳ Replying to tweet ${tweet.inReplyToStatusId}`);
    }
    console.log('─'.repeat(50));
  }
} else {
  console.error(`Failed to fetch thread: ${result.error}`);
}
```

--------------------------------

### Get Following and Followers - Bird CLI

Source: https://context7.com/steipete/bird/llms.txt

Retrieve lists of users that you are following and users that are following you. Supports fetching this information for a specific user by their ID. JSON output is available for programmatic processing.

```bash
# Get users you follow
bird following -n 20

# Get users following you
bird followers -n 20

# Get following/followers for specific user (by user ID)
bird following --user 44196397 -n 10
bird followers --user 44196397 -n 10 --json
```

--------------------------------

### Get Following and Followers for a User

Source: https://context7.com/steipete/bird/llms.txt

Fetches the list of users a given user is following and their followers. It first retrieves the current logged-in user's information and then uses their ID to fetch their following and followers lists. It also demonstrates how to fetch this information for another specified user ID.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({ cookies });

// Get current user info first
const currentUser = await client.getCurrentUser();

if (!currentUser.success || !currentUser.user) {
  throw new Error(`Failed to get current user: ${currentUser.error}`);
}

console.log(`Logged in as: @${currentUser.user.username} (${currentUser.user.name})`);
console.log(`User ID: ${currentUser.user.id}\n`);

// Get users you follow
const followingResult = await client.getFollowing(currentUser.user.id, 20);

if (followingResult.success && followingResult.users) {
  console.log(`You follow ${followingResult.users.length} users:\n`);

  for (const user of followingResult.users) {
    console.log(`@${user.username} - ${user.name}`);
    if (user.description) {
      console.log(`  ${user.description.substring(0, 80)}...`);
    }
    console.log(`  ${user.followersCount?.toLocaleString()} followers`);
    if (user.isBlueVerified) {
      console.log(`  ✓ Verified`);
    }
    console.log();
  }
}

// Get your followers
const followersResult = await client.getFollowers(currentUser.user.id, 20);

if (followersResult.success && followersResult.users) {
  console.log(`\nYou have ${followersResult.users.length} followers`);
}

// Get following/followers for another user
const otherUserId = '44196397';  // @elonmusk
const othersFollowing = await client.getFollowing(otherUserId, 10);
```

--------------------------------

### Get Bookmarks and Likes - Bird CLI

Source: https://context7.com/steipete/bird/llms.txt

Retrieve lists of bookmarked tweets and liked tweets. Allows filtering bookmarks by folder ID and can output results in JSON format. Useful for managing and analyzing your saved or appreciated content.

```bash
# Get your bookmarks
bird bookmarks -n 20

# Get bookmarks from specific folder
bird bookmarks --folder-id 123456789123456789 -n 10

# Get liked tweets
bird likes -n 20 --json
```

--------------------------------

### Reply to a Tweet (TypeScript)

Source: https://context7.com/steipete/bird/llms.txt

This code example demonstrates how to reply to an existing tweet. It requires the `tweetId` of the tweet to reply to and the reply content. The `reply` method is called with these parameters, and the result indicates whether the reply was successful, providing the new tweet ID upon success.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'firefox' });
const client = new TwitterClient({ cookies });

const tweetId = '1234567890123456789';
const replyText = 'Great point! I completely agree. 👍';

const result = await client.reply(replyText, tweetId);

if (result.success) {
  console.log(`Reply posted: https://x.com/i/status/${result.tweetId}`);
} else {
  console.error(`Failed to post reply: ${result.error}`);
}

```

--------------------------------

### Get Replies to a Tweet using Twitter API

Source: https://context7.com/steipete/bird/llms.txt

Fetches direct replies to a specific tweet identified by its ID. This function requires Twitter credentials and returns an array of reply tweets.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({ cookies });

const tweetId = '1234567890123456789';
const result = await client.getReplies(tweetId);

if (result.success && result.tweets) {
  console.log(`Found ${result.tweets.length} direct replies:\n`);

  for (const reply of result.tweets) {
    console.log(`@${reply.author.username} replied:`);
    console.log(reply.text);
    console.log(`  ${reply.likeCount} likes\n`);
  }
} else {
  console.error(`Failed to fetch replies: ${result.error}`);
}
```

--------------------------------

### Get Bookmarked Tweets using Twitter API

Source: https://context7.com/steipete/bird/llms.txt

Retrieves a user's bookmarked tweets. It can fetch all bookmarks or bookmarks from a specific folder, identified by a folder ID. Requires Twitter credentials and returns an array of bookmarked tweets.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({ cookies });

// Get all bookmarks
const result = await client.getBookmarks(20);

if (result.success && result.tweets) {
  console.log(`Found ${result.tweets.length} bookmarked tweets:\n`);

  for (const tweet of result.tweets) {
    console.log(`@${tweet.author.username}: ${tweet.text.substring(0, 100)}...`);
    console.log(`  URL: https://x.com/${tweet.author.username}/status/${tweet.id}\n`);
  }
} else {
  console.error(`Failed to fetch bookmarks: ${result.error}`);
}

// Get bookmarks from a specific folder
// Folder ID from URL: https://x.com/i/bookmarks/<folder-id>
const folderId = '123456789123456789';
const folderResult = await client.getBookmarkFolderTimeline(folderId, 10);

if (folderResult.success && folderResult.tweets) {
  console.log(`Folder has ${folderResult.tweets.length} bookmarks`);
}
```

--------------------------------

### Get Liked Tweets using Twitter API

Source: https://context7.com/steipete/bird/llms.txt

Fetches tweets that a user has liked. This function requires Twitter credentials and returns an array of tweets the user has liked, including the timestamp when they were liked.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({ cookies });

const result = await client.getLikes(20);

if (result.success && result.tweets) {
  console.log(`Found ${result.tweets.length} liked tweets:\n`);

  for (const tweet of result.tweets) {
    console.log(`@${tweet.author.username}: ${tweet.text}`);
    console.log(`  Liked on: ${tweet.createdAt}\n`);
  }
} else {
  console.error(`Failed to fetch likes: ${result.error}`);
}
```

--------------------------------

### Configuration File - Bird CLI

Source: https://context7.com/steipete/bird/llms.txt

Configure Bird CLI behavior using JSON5 files. Supports global configuration in `~/.config/bird/config.json5` and project-specific configuration in `./.birdrc.json5`. Allows setting cookie sources, browser profiles, timeouts, and quote depth.

```bash
# Global config: ~/.config/bird/config.json5
# Project config: ./.birdrc.json5

cat > ~/.config/bird/config.json5 << 'EOF'
{
  // Cookie source priority order
  cookieSource: ["firefox", "safari", "chrome"],

  // Browser profile settings
  firefoxProfile: "default-release",
  chromeProfile: "Default",

  // Timeout settings (milliseconds)
  cookieTimeoutMs: 30000,
  timeoutMs: 20000,

  // Max depth for quoted tweets in JSON output
  quoteDepth: 1
}
EOF

# Environment variable shortcuts
export BIRD_TIMEOUT_MS=30000
export BIRD_COOKIE_TIMEOUT_MS=30000
export BIRD_QUOTE_DEPTH=2
```

--------------------------------

### Authentication and Configuration - Bird CLI

Source: https://context7.com/steipete/bird/llms.txt

Manage authentication and configure the Bird CLI. Supports various methods including checking the current logged-in account, credential availability, using specific browsers, environment variables, CLI flags, and global options like timeouts.

```bash
# Check which account you're logged in as
bird whoami

# Check credential availability
bird check

# Use specific browser
bird --cookie-source chrome whoami
bird --chrome-profile "Profile 1" whoami

# Use environment variables
export AUTH_TOKEN="your_auth_token"
export CT0="your_ct0_token"
bird whoami

# Use CLI flags (highest priority)
bird --auth-token "..." --ct0 "..." whoami

# Global options
bird --timeout 30000 search "query"          # 30 second timeout
bird --quote-depth 2 read 1234567890         # Include nested quotes
bird --plain search "query"                  # No emoji, no color
bird --no-color --no-emoji read 1234567890   # Script-friendly output
```

--------------------------------

### Post a Tweet with Media (TypeScript)

Source: https://context7.com/steipete/bird/llms.txt

This snippet illustrates how to upload media (image, GIF, video) and then post a tweet that includes the uploaded media. It first uses `uploadMedia` with the file buffer and MIME type, then posts the tweet using the returned media ID. Error handling is included for both media upload and tweet posting.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';
import { readFileSync } from 'node:fs';

const { cookies } = await resolveCredentials({ cookieSource: 'chrome' });
const client = new TwitterClient({ cookies });

// Upload media first
const imageBuffer = readFileSync('./photo.jpg');
const uploadResult = await client.uploadMedia({
  data: imageBuffer,
  mimeType: 'image/jpeg',
  alt: 'A beautiful sunset over the mountains'
});

if (!uploadResult.success || !uploadResult.mediaId) {
  throw new Error(`Media upload failed: ${uploadResult.error}`);
}

// Post tweet with attached media
const result = await client.tweet(
  'Check out this amazing view! 🌄',
  [uploadResult.mediaId]
);

if (result.success) {
  console.log(`Tweet with media posted: https://x.com/i/status/${result.tweetId}`);
} else {
  console.error(`Failed to post tweet: ${result.error}`);
}

```

--------------------------------

### Manage Runtime Query IDs for API Requests

Source: https://context7.com/steipete/bird/llms.txt

Explains how the Bird library handles Twitter API query IDs, which are essential for GraphQL requests. It shows how query IDs are automatically refreshed on 404 errors and how to manually refresh them if needed. It also provides information on checking the cache status and details of available operations.

```typescript
import { TwitterClient, resolveCredentials, runtimeQueryIds } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({ cookies });

// Query IDs are automatically refreshed on 404 errors
// Manual refresh if needed:
await runtimeQueryIds.refresh(['TweetDetail', 'SearchTimeline'], { force: true });

// Get current query ID cache info
const info = await runtimeQueryIds.getSnapshotInfo();

if (info) {
  console.log(`Query IDs cached at: ${info.cachePath}`);
  console.log(`Fetched: ${info.snapshot.fetchedAt}`);
  console.log(`Fresh: ${info.isFresh}`);
  console.log(`Age: ${Math.round(info.ageMs / 1000 / 60)} minutes`);
  console.log(`Operations: ${Object.keys(info.snapshot.ids).length}`);

  // Available operations:
  // CreateTweet, CreateRetweet, FavoriteTweet, TweetDetail, SearchTimeline,
  // UserArticlesTweets, Bookmarks, Following, Followers, Likes, BookmarkFolderTimeline
}

// Cache location: ~/.config/bird/query-ids-cache.json
// Override with: BIRD_QUERY_IDS_CACHE=/custom/path.json
// TTL: 24 hours (stale cache still used but marked not fresh)
```

--------------------------------

### Tweet with Text and Media - Bird CLI

Source: https://context7.com/steipete/bird/llms.txt

Post a tweet with text content and optional media attachments (images or videos). Supports multiple media files per tweet, with corresponding alt text for accessibility. Note that videos cannot be mixed with images in a single tweet.

```bash
# Simple tweet
bird tweet "Hello from bird! 🐦"

# Tweet with media attachments
bird tweet "Check out these photos!" \
  --media photo1.jpg \
  --media photo2.png \
  --alt "First photo description" \
  --alt "Second photo description"

# Tweet with video (max 1 video, no mixing with images)
bird tweet "Watch this!" --media video.mp4
```

--------------------------------

### Resolve Twitter API Credentials

Source: https://context7.com/steipete/bird/llms.txt

Demonstrates how to resolve Twitter API credentials using various methods, prioritizing explicit parameters, environment variables (AUTH_TOKEN, CT0), and then browser cookies (Firefox, Safari, Chrome). It includes options for specifying browser profiles and timeouts.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

// Set environment variables (alternative to browser cookies)
process.env.AUTH_TOKEN = 'your_auth_token_here';
process.env.CT0 = 'your_ct0_token_here';

// Credentials will be resolved in this order:
// 1. Explicit authToken/ct0 parameters
// 2. Environment variables (AUTH_TOKEN, CT0 or TWITTER_AUTH_TOKEN, TWITTER_CT0)
// 3. Browser cookies (safari, chrome, firefox)

const { cookies, warnings } = await resolveCredentials({
  cookieSource: ['firefox', 'safari', 'chrome'],  // Priority order
  firefoxProfile: 'default-release',
  chromeProfile: 'Default',
  cookieTimeoutMs: 30000
});

if (warnings.length > 0) {
  console.warn('Credential warnings:', warnings);
}

const client = new TwitterClient({
  cookies,
  timeoutMs: 20000
});
```

--------------------------------

### Initialize Twitter Client with Browser Cookies (TypeScript)

Source: https://context7.com/steipete/bird/llms.txt

This snippet demonstrates how to initialize the TwitterClient using browser session cookies. It uses `resolveCredentials` to automatically detect and extract cookies from Safari, Chrome, or Firefox. The client is configured with these cookies, an optional request timeout, and a quote depth for handling quoted tweets. Error handling is included for missing credentials.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

// Auto-detect cookies from Safari (default priority: safari, chrome, firefox)
const { cookies, warnings } = await resolveCredentials({
  cookieSource: 'safari'
});

// Display any warnings about cookie extraction
for (const warning of warnings) {
  console.warn(warning);
}

// Verify credentials are available
if (!cookies.authToken || !cookies.ct0) {
  throw new Error('Missing required credentials. Please log in to x.com in your browser.');
}

// Create client instance
const client = new TwitterClient({
  cookies,
  timeoutMs: 20000,      // Request timeout (optional)
  quoteDepth: 1          // Max depth for quoted tweets (default: 1)
});

console.log(`Authenticated via: ${cookies.source}`);

```

--------------------------------

### Handle API Errors and Implement Fallbacks

Source: https://context7.com/steipete/bird/llms.txt

Illustrates how to handle errors returned by the Twitter API client. The library's methods return result objects with a `success` flag. This snippet shows how to check for errors and implement specific fallback logic for common issues like automated requests, rate limiting, 404 errors (query ID issues), and timeouts. It also lists automatic fallbacks provided by the library.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({
  cookies,
  timeoutMs: 10000  // 10 second timeout
});

// All methods return result objects with success flags
const result = await client.tweet('Test post');

if (!result.success) {
  // Handle specific error cases
  if (result.error?.includes('automated request')) {
    console.error('Detected as automated. Fallback to legacy endpoint attempted.');
  } else if (result.error?.includes('HTTP 429')) {
    console.error('Rate limited. Wait before retrying.');
  } else if (result.error?.includes('HTTP 404')) {
    console.error('Query ID invalid. Automatic refresh attempted.');
  } else if (result.error?.includes('timeout')) {
    console.error('Request timed out. Try increasing timeoutMs.');
  } else {
    console.error(`Error: ${result.error}`);
  }

  process.exit(1);
}

// The library includes automatic fallbacks:
// - GraphQL error 226 ("automated request") → legacy statuses/update.json endpoint
// - GraphQL 404 → automatic query ID refresh + retry
// - TweetDetail/SearchTimeline → rotate through known fallback query IDs
```

--------------------------------

### Query ID Management - Bird CLI

Source: https://context7.com/steipete/bird/llms.txt

Manage GraphQL query IDs used by the Bird CLI. Allows viewing cached IDs, forcing a fresh scrape from X client bundles, and specifying a custom cache location via environment variables. Includes details on cache TTL and auto-refresh behavior.

```bash
# Show cached GraphQL query IDs
bird query-ids

# Force refresh query IDs (scrapes X client bundles)
bird query-ids --fresh

# JSON output
bird query-ids --fresh --json

# Cache location and behavior:
# - Default: ~/.config/bird/query-ids-cache.json
# - TTL: 24 hours
# - Auto-refresh on GraphQL 404 errors
# - Override: BIRD_QUERY_IDS_CACHE=/custom/path.json
```

--------------------------------

### Read and Explore Tweets - Bird CLI

Source: https://context7.com/steipete/bird/llms.txt

Retrieve and read individual tweets, including Notes and Articles, using their URL or ID. Supports fetching replies to a tweet and its full conversation thread. Output can be formatted as JSON for programmatic use.

```bash
# Read a tweet (supports Notes and Articles)
bird read https://x.com/user/status/1234567890123456789

# Shorthand syntax
bird 1234567890123456789

# JSON output
bird read 1234567890123456789 --json

# Get replies to a tweet
bird replies 1234567890123456789
bird replies https://x.com/user/status/1234567890123456789 --json

# Get full conversation thread
bird thread 1234567890123456789
bird thread https://x.com/user/status/1234567890123456789 --json
```

--------------------------------

### Specify Browser for Cookies - Bird CLI

Source: https://context7.com/steipete/bird/llms.txt

Configure the Bird CLI to use cookies from specific browsers for authentication. Supports Firefox and Chrome, with options to specify a default profile or a named profile for cookie extraction.

```bash
# Specify browser for cookie extraction
bird --cookie-source firefox tweet "Using Firefox cookies"
bird --firefox-profile default-release tweet "Using specific profile"
```

--------------------------------

### Search Tweets - Bird CLI

Source: https://context7.com/steipete/bird/llms.txt

Perform searches on Twitter (X) using various criteria, including keywords, user mentions, and advanced query syntax. Supports limiting the number of results and outputting results in JSON format. Useful for data collection and analysis.

```bash
# Basic search
bird search "from:steipete" -n 10

# Search mentions
bird mentions -n 20
bird mentions --user @steipete -n 5

# Complex queries
bird search "typescript OR javascript" -n 50
bird search '"exact phrase" since:2024-01-01' -n 30 --json
```

--------------------------------

### Read a Tweet's Details (TypeScript)

Source: https://context7.com/steipete/bird/llms.txt

This snippet shows how to fetch detailed information about a specific tweet using its ID. The `getTweet` method is used, and upon successful retrieval, it provides access to the tweet's author, text, statistics (likes, retweets, replies), creation date, and any quoted tweet details. Error handling is included for fetch failures.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({ cookies, quoteDepth: 2 });

const tweetId = '1234567890123456789';
const result = await client.getTweet(tweetId);

if (result.success && result.tweet) {
  const tweet = result.tweet;
  console.log(`@${tweet.author.username} (${tweet.author.name}):`);
  console.log(tweet.text);
  console.log(`
Stats: ${tweet.likeCount} likes, ${tweet.retweetCount} retweets, ${tweet.replyCount} replies`);
  console.log(`Posted: ${tweet.createdAt}`);

  // Check for quoted tweet
  if (tweet.quotedTweet) {
    console.log(`
Quoted: @${tweet.quotedTweet.author.username}: ${tweet.quotedTweet.text}`);
  }
} else {
  console.error(`Failed to fetch tweet: ${result.error}`);
}

```

--------------------------------

### Search Tweets using Twitter API

Source: https://context7.com/steipete/bird/llms.txt

Searches for tweets based on a given query. It requires Twitter credentials and returns a list of tweets matching the search criteria. Supports advanced search queries like mentions, keywords, date ranges, and filters.

```typescript
import { TwitterClient, resolveCredentials } from '@steipete/bird';

const { cookies } = await resolveCredentials({ cookieSource: 'safari' });
const client = new TwitterClient({ cookies });

// Search for tweets from a specific user
const searchResult = await client.search('from:steipete', 50);

if (searchResult.success && searchResult.tweets) {
  console.log(`Found ${searchResult.tweets.length} tweets`);

  for (const tweet of searchResult.tweets) {
    console.log(`\n@${tweet.author.username}: ${tweet.text}`);
    console.log(`  ${tweet.likeCount} ❤️  ${tweet.retweetCount} 🔁  ${tweet.replyCount} 💬`);
  }
} else {
  console.error(`Search failed: ${searchResult.error}`);
}

// Advanced search queries
const queries = [
  '@username',
  'from:username',
  'to:username',
  'keyword1 keyword2',
  '"exact phrase"',
  'keyword -excluded',
  'keyword since:2024-01-01',
  'keyword filter:media',
  'keyword filter:replies',
];
```

--------------------------------

### Reply to a Tweet - Bird CLI

Source: https://context7.com/steipete/bird/llms.txt

Reply to existing tweets using either their unique ID or a full URL. Supports adding media attachments and alt text to your replies. This functionality allows for direct engagement with specific tweets.

```bash
# Reply using tweet ID
bird reply 1234567890123456789 "Great point!"

# Reply using full URL
bird reply https://x.com/user/status/1234567890123456789 "Totally agree!"

# Reply with media
bird reply 1234567890123456789 "Here's my response" \
  --media screenshot.png \
  --alt "Screenshot showing the issue"
```

--------------------------------

### Refresh Query IDs (Bash)

Source: https://github.com/steipete/bird/blob/main/README.md

Command to manually refresh the GraphQL query IDs used by the `bird` CLI. This is useful when X updates its internal structures, potentially invalidating existing query IDs. Running this command ensures the CLI uses the latest valid IDs for GraphQL operations.

```bash
bird query-ids --fresh
```
Tokens:
Raw