bird

Bird - X/Twitter CLI

X/Twitter のコンテンツを操作するための bird CLI ツールの使用ガイドです。

クイックスタート

bird をグローバルにインストールします：

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
# or
brew install steipete/tap/bird

認証を確認します：

bird whoami          # Show logged-in account
bird check           # Check available credentials

よく使うタスク

ツイートとスレッドを読む

# Read a single tweet
bird read <tweet-url-or-id>
bird <tweet-url-or-id>              # shorthand

# Read a thread (tweet + replies)
bird thread <tweet-url-or-id>

# Get replies only
bird replies <tweet-url-or-id>

# Output as JSON for processing
bird read <id> --json
bird thread <id> --json --max-pages 3

ツイートを検索する

# Basic search
bird search "query" -n 10

# Search from a specific user
bird search "from:username" -n 20

# Get all results (paginated)
bird search "query" --all --json

# Search with date filters
bird search "query since:2024-01-01" -n 50

ユーザーのコンテンツを取得する

# User's tweets
bird user-tweets @username -n 20
bird user-tweets @username -n 50 --json

# User mentions
bird mentions --user @username -n 10

ブックマークを管理する

# List bookmarks
bird bookmarks -n 20
bird bookmarks --all --json

# From a specific folder
bird bookmarks --folder-id <id> -n 10

# Remove a bookmark
bird unbookmark <tweet-id-or-url>

ニュースとトレンドを取得する

# AI-curated news
bird news --ai-only -n 10

# Sports/Entertainment news
bird news --sports -n 15
bird news --entertainment -n 10

# Include related tweets
bird news --with-tweets --tweets-per-item 3 -n 10

# Trending topics
bird trending -n 10

ツイートを投稿する（注意して使用してください）

# Send a tweet
bird tweet "hello world"

# Reply to a tweet
bird reply <tweet-id-or-url> "my reply"

JSON 出力を処理する

jq を使って、JSON 出力から特定のフィールドを抽出します：

# Get tweet text only
bird read <id> --json | jq -r '.text'

# Get user info
bird user-tweets @user -n 5 --json | jq '.[] | {name: .user.name, handle: .user.screen_name}'

# Extract media URLs
bird read <id> --json | jq -r '.media[]?.url'

# Save to file
bird user-tweets @user --all --json > tweets.json

認証

Bird は Cookie ベースの認証を使用します（API キーは不要です）。 --auth-token／--ct0 を使って Cookie を直接渡すか、ブラウザーの Cookie には --cookie-source を使用します。

ブラウザーの Cookie ソース：

• Safari、Chrome、Firefox（macOS）
• Chromium の派生ブラウザー（Arc／Brave など）：--chrome-profile-dir を使用します
• --cookie-source で Cookie の順序を選択し、特定の Firefox プロファイルには --firefox-profile を指定します
• --cookie-source は繰り返し指定できます：safari|chrome|firefox|all|none

設定ファイル

グローバル：~/.config/bird/config.json5
プロジェクト：./.birdrc.json5

例：

{
  cookieSource: ["chrome"],
  chromeProfileDir: "/path/to/Arc/Profile",
  chromeProfile: "Default",
  firefoxProfile: "default-release",
  cookieTimeoutMs: 10000,
  timeoutMs: 20000,
  quoteDepth: 1
}

環境変数：

• BIRD_TIMEOUT_MS
• BIRD_COOKIE_TIMEOUT_MS
• BIRD_QUOTE_DEPTH
• BIRD_QUERY_IDS_CACHE

重要な注意事項

• 非公開の X/Twitter GraphQL API を使用しているため、予告なく動作しなくなる可能性があります
• 推奨：読み取りのみに使用してください。ツイートの投稿によってブロックされる可能性があります。
• レート制限が適用されます。リクエスト間に遅延を加えるには --delay <ms> を使用してください
• ページネーション（対応している場合）：search、bookmarks、likes、following、followers では、--all または --max-pages と併せて --cursor を指定する必要があります。list-timeline では --max-pages は --all として扱われます

トラブルシューティング

クエリ ID が古い（404 エラー）：

bird query-ids --fresh

クエリ ID のキャッシュ：

• デフォルト：~/.config/bird/query-ids-cache.json
• 上書き：BIRD_QUERY_IDS_CACHE=/path/to/file.json

Cookie の抽出に失敗する場合：

• ブラウザーで X/Twitter にログインしていることを確認します
• --cookie-source の順序を変えて試します
• Arc／Brave の場合は、--chrome-profile-dir を指定します

フラグ／環境変数による認証に失敗する場合：

• --auth-token と --ct0 が同じセッションのものであることを確認します
• 簡単な動作確認として、フラグではなくブラウザーの Cookie を試します

リファレンス

コマンドの詳細については、references/commands.md を参照してください。