bird-fast

bird CLI

既存のブラウザーセッションを使って認証する、X/Twitter 用のコマンドラインインターフェースです。API キーや OAuth の設定は不要です。

概要

bird は、クエリ ID を自動管理しながら Twitter の内部 GraphQL API を利用する、TypeScript ベースの CLI です。Safari、Chrome、Firefox から認証用 Cookie を抽出します。

主な機能：

• ブラウザー Cookie による設定不要の認証
• ツイートのライフサイクル全般に対応：投稿、返信、読み取り、検索
• メディアのアップロード（画像、GIF、動画）と代替テキスト
• 複数の出力形式（人間が読みやすい形式、JSON、プレーン形式）
• GraphQL クエリ ID の自動更新と REST API へのフォールバック

使用する場面

• スクリプトや自動化処理からツイートや返信を投稿する
• ツイートのスレッドをプログラムで読み取り、分析する
• メンションや特定のコンテンツを検索する
• CLI から Twitter のアクティビティを監視する

前提条件

• Node.js >= 22 または Homebrew（スタンドアロンバイナリの場合）
• ブラウザーでのログイン：Safari、Chrome、Firefox のいずれかで x.com にログインしている必要があります

インストール

# npm
npm install -g @steipete/bird

# pnpm
pnpm add -g @steipete/bird

# bun
bun add -g @steipete/bird

# Homebrew (macOS — standalone binary, no Node.js required)
brew install steipete/tap/bird

# One-shot execution (no install)
bunx @steipete/bird whoami
npx @steipete/bird whoami

認証

bird は次の3段階の優先順位で認証情報を取得します。

優先順位	ソース	設定方法
1（最高）	CLI フラグ	--auth-token、--ct0
2	環境変数	AUTH_TOKEN、CT0（または TWITTER_AUTH_TOKEN、TWITTER_CT0）
3（デフォルト）	ブラウザー Cookie	Safari → Chrome → Firefox の順に自動抽出

認証を確認する：

bird whoami    # Shows authenticated user
bird check     # Shows credential source

クイックスタート

# Post a tweet
bird tweet "Hello from the terminal!"

# Read a tweet
bird read https://x.com/user/status/1234567890123456789

# Reply to a tweet
bird reply 1234567890123456789 "Great point!"

# Search tweets
bird search "from:elonmusk" -n 20

# View your mentions
bird mentions

コマンドリファレンス

書き込みコマンド

tweet

メディアを添付して、新しいツイートを投稿します。

bird tweet "<text>" [options]

# Options
--media <path>    Attach media file (repeatable, up to 4 images/GIFs or 1 video)
--alt <text>      Alt text for corresponding --media (repeatable)

# Examples
bird tweet "Check this out!"
bird tweet "Photo gallery" --media img1.jpg --alt "First photo" --media img2.jpg --alt "Second"
bird tweet "Demo video" --media demo.mp4

reply

既存のツイートに返信します。

bird reply <tweet-id-or-url> "<text>" [options]

# Examples
bird reply 1234567890123456789 "I agree!"
bird reply https://x.com/user/status/1234567890123456789 "Great thread!"
bird reply 1234567890123456789 "Here's a screenshot" --media shot.png --alt "Screenshot"

読み取りコマンド

read

単一のツイートを取得します。通常のツイート、Notes（長文形式）、記事に対応しています。

bird read <tweet-id-or-url>

# Shorthand: just provide the ID or URL
bird 1234567890123456789
bird https://x.com/user/status/1234567890123456789

replies / thread

bird replies <tweet-id-or-url>    # All replies to a tweet
bird thread <tweet-id-or-url>     # Full conversation thread

検索コマンド

search

bird search "<query>" [-n <count>]

# Examples
bird search "claude ai" -n 20
bird search "from:anthropic"
bird search "@username"

Twitter の高度な検索構文に対応しています：from:、to:、since:、until:、filter:links など。

mentions / bookmarks

bird mentions [-u <handle>] [-n <count>]    # Mentions of a user (defaults to you)
bird bookmarks [-n <count>]                  # Your bookmarked tweets

ユーティリティコマンド

bird whoami                        # Show authenticated user
bird check                         # Verify credentials and show source
bird query-ids [--fresh] [--json]  # Inspect/refresh GraphQL query ID cache
bird help [command]                # Show help

グローバルオプション

オプション	説明
--auth-token <token>	Twitter の auth_token Cookie
--ct0 <token>	Twitter の ct0 Cookie
--cookie-source <source>	ブラウザーの優先順位：safari、chrome、firefox（複数指定可能）
--chrome-profile <name>	Chrome のプロファイル名
--firefox-profile <name>	Firefox のプロファイル名
--timeout <ms>	リクエストのタイムアウト（ミリ秒）
--plain	安定した出力：絵文字と色を無効化（スクリプトに適しています）
--no-emoji	出力の絵文字を無効化
--no-color	ANSI カラーを無効化
--json	JSON として出力（コマンド固有）

メディア添付ファイル

種類	拡張子	上限
画像	.jpg、.jpeg、.png、.webp	最大4件
GIF	.gif	最大4件
動画	.mp4、.m4v、.mov	1件のみ

動画と画像／GIFは混在できません。

# Alt text for accessibility
bird tweet "Three photos" \
  --media photo1.jpg --alt "Beach sunset" \
  --media photo2.jpg --alt "Mountain view" \
  --media photo3.jpg --alt "City skyline"

出力形式

形式	フラグ	用途
人間が読みやすい形式	（デフォルト）	対話型ターミナル
プレーン形式	--plain	スクリプト（絵文字／色なし）
JSON	--json	プログラムによる解析

# Parse tweet data in a script
bird read 1234567890123456789 --json | jq '.text'

# Mention monitoring
bird mentions -n 50 --json | jq '.[] | {user: .user.screen_name, text: .text}'

設定

オプションの JSON5 設定ファイル：

場所	範囲
~/.config/bird/config.json5	グローバル
./.birdrc.json5	プロジェクト固有

// Example config
{
  cookieSource: ["firefox", "safari"],
  firefoxProfile: "default-release",
  timeoutMs: 20000
}

使用例

日次自動化スクリプト

#!/bin/bash
DATE=$(date +"%B %d, %Y")
bird tweet "Daily status for $DATE: All systems operational. #status"

スレッドの分析

# Get all replies to a viral tweet as JSON
bird replies https://x.com/user/status/1234567890123456789 --json | \
  jq '.[] | {user: .user.screen_name, text: .text, likes: .favorite_count}'

複数画像を使った製品投稿

bird tweet "Product launch gallery 🚀" \
  --media hero.png --alt "Product hero shot" \
  --media feature1.png --alt "Feature overview" \
  --media feature2.png --alt "Technical specs" \
  --media pricing.png --alt "Pricing table"

メンションを監視して返信

#!/bin/bash
bird mentions -n 20 --json | jq -r '.[] | "\(.id) \(.user.screen_name): \(.text)"'

ベストプラクティス

• スクリプトでは --json を使用する — 出力をプログラムで解析する場合は必ず使用してください
• CI/CD では --plain を使用する — ログでの絵文字や色の問題を回避できます
• 代替テキストを追加する — 画像を添付する際は必ず --alt を含めてください
• クエリ ID を事前に更新する — bird を数日間使用していない場合は、bird query-ids --fresh を実行してください
• 自動化では環境変数を設定する — スクリプトではブラウザーの Cookie ではなく、AUTH_TOKEN / CT0 を使用してください
• レート制限に対処する — Twitter はリクエストを制限します。一括自動化スクリプトでは遅延（sleep）を追加してください

トラブルシューティング

「認証トークンが見つかりません」

# Verify you're logged into x.com in your browser
# Try specifying the browser explicitly
bird whoami --cookie-source safari

# Or set credentials via environment
export AUTH_TOKEN="your-auth-token"
export CT0="your-ct0-token"
bird whoami

GraphQL 404 エラー

クエリ ID が古くなっている可能性があります。キャッシュを更新してください：

bird query-ids --fresh

エラー 226（自動化を検出）

bird は自動的に REST API にフォールバックします。問題が続く場合は、数分待ってから再試行してください。

誤ったアカウントが検出される

# Multiple browser profiles may have different sessions
bird whoami --cookie-source chrome --chrome-profile "Profile 1"

終了コード

コード	意味
0	成功
1	実行時エラー（ネットワーク、認証、API）
2	使用方法が無効（不明なコマンド、不正な引数）

技術的な注意事項

• Twitter のプライベート GraphQL API エンドポイントを使用します
• クエリ ID は ~/.config/bird/query-ids-cache.json にキャッシュされます（TTL は 24 時間）
• 404 エラー時にクエリ ID を自動更新します
• エラー 226 の場合は REST API（statuses/update.json）にフォールバックします
• Twitter が内部 API を変更すると動作しなくなる可能性があります

リソース

• GitHub リポジトリ — ソースコードと課題
• 変更履歴 — バージョン履歴