xfetch

xfetch

開発者向けの有料 API の代わりに、ユーザー自身のログイン Cookie を使って、X（Twitter）の公開データ（プロフィール、ツイート、スレッド、検索、フォロワー）を取得します。このスキルには、X の GraphQL API を直接呼び出し、エージェントが解析できる構造化データを出力する、自己完結型の CLI scripts/xfetch.py が含まれています。

動作を維持する仕組み（重要なアーキテクチャ）： X のスクレイピングで難しいのは、X がサイトを絶えず変更することです。数週間ごとに GraphQL クエリ ID をローテーションし、エンドポイントを GET と POST の間で移行させ、レスポンス JSON の構造を変更します。この CLI では、こうした要素を分離しているため、ある箇所に問題が起きてもすべてが停止することはありません。

• twikit パッケージに含まれる最新のクエリ ID と機能フラグを再利用します（pip install -U twikit で最新の状態に保てます）。そのため、頻繁にローテーションされる値を手動で管理する必要はありません。
• 独自に HTTP リクエストと JSON 解析を行うことで、twikit で問題が起きやすい 2 つの箇所を回避します。（1）ホームページをスクレイピングして取得するボット対策用のトランザクション ID。この CLI は、読み取りエンドポイントで X が受け入れる無害なプレースホルダー x-client-transaction-id を送信します。（2）レスポンスモデルのレイヤー。この CLI は生の JSON を独自に解析します。また、404 が返された場合は GET と POST を自動的に切り替えるため、X が移行したエンドポイントも引き続き利用できます。

つまり、あるコマンドが突然誰にとってもエラーになる場合、まずは pip install -U twikit を実行してみてください（クエリ ID が更新されます）。それで解決しない場合は、X がレスポンスの構造を変更しています。scripts/xfetch.py のパーサーを確認してください。

エージェント向けのインターフェース仕様

scripts/xfetch.py は、予期しない動作を避けながらループ内で実行できるように設計されています。文章をスクレイピングするのではなく、次の 3 つのチャネルを利用してください。

• stdout にはデータペイロードのみが出力されます（デフォルトは JSON）。リダイレクトまたはパイプで使用してください。ほかの内容は出力されません。
• stderr には人間向けのステータス（✓ Saved…）とエラーが出力されます。原因を調べるときに読み取り、解析時には無視してください。
• 終了コードが成功・失敗の判定に使えます。0 = 成功、1 = エラー、2 = 認証されていない、3 = レート制限中（stderr に rate_limit_reset=<epoch> が出力されます）、64 = 使用方法のエラー（フラグまたは引数が不正です。コマンドを修正し、再認証はしないでください）。stderr のテキストではなく、終了コードに基づいて処理を分岐してください。

セットアップ（環境ごとに 1 回）

1. Python を確認し、twikit をインストールします（システムパッケージに触れずに済む仮想環境の利用をおすすめします）。

   python3 -m pip install -r scripts/requirements.txt   # installs twikit>=2.3.3
   

2. CLI を読み込めることを確認します。

   python3 scripts/xfetch.py --version    # -> xfetch-skill 0.3
   

すべてのコマンドは、このスキルに含まれるスクリプトを使って、python3 scripts/xfetch.py <command> … の形式で実行してください。

最初に認証してください — 最もよくある失敗の原因です

すべてのデータコマンドには、ユーザーの X Cookie（auth_token と ct0）が必要です。これらがない場合、コマンドは標準エラー出力に Not authenticated. と表示し、終了コード 2 で終了します。認証は委任されます。人間が一度設定すると、CLI がセッションを ~/.config/xfetch/cookies.json に保存するので、以降はそれを再利用します。認証情報のライフサイクルを管理する必要はなく、存在することを確認するだけです。

必ず最初にこれを実行し、終了コードに応じて処理を分岐してください。

python3 scripts/xfetch.py auth check

認証されていない場合は、次の優先順で人間に認証情報の提供を依頼してください。

• ログイン済みのブラウザーから取得する（最も便利です。ブラウザーのストアから x.com の Cookie を直接読み取るため、コピー＆ペーストは不要です）。

  python3 scripts/xfetch.py auth extract --browser chrome
  # supported: chrome, chromium, firefox, safari, edge, brave, arc, opera, vivaldi, librewolf
  

  browser_cookie3（requirements.txt に含まれています）が必要です。macOS ではキーチェーンへのアクセスを求められる場合があります。これは OS が Cookie の復号キーを渡す処理であり、想定どおりの動作です。

• Cookie ファイルをインポートする（読み取り用ツールのないブラウザーに最適です。たとえば、ChatGPT Atlas、Orion、または Chromium のフォークなど）。「Get cookies.txt」ブラウザー拡張機能で Cookie をエクスポートします（Netscape cookies.txt と JSON のどちらも使用できます）。次に、CLI でファイルを指定すると、auth_token と ct0 が自動的に抽出されます。

  python3 scripts/xfetch.py auth import --file ~/Downloads/x.com_cookies.txt
  

• Cookie トークンを貼り付ける（どのブラウザーでも使えます）。DevTools → Application → Cookies → https://x.com を開き、auth_token と ct0 の値をコピーしてから、次を実行します。

  python3 scripts/xfetch.py auth set --auth-token <token> --ct0 <token>
  

• 環境変数（CI や一時的な利用に適しています。ディスクには何も保存されません）。

  XFETCH_AUTH_TOKEN=<token> XFETCH_CT0=<token> python3 scripts/xfetch.py user @handle
  

• ユーザー名とパスワードでログインする（twikit が実際にログインします。CAPTCHA や 2FA が発生する場合があります。TOTP ベースの 2FA には --totp を指定してください）。

  python3 scripts/xfetch.py auth login --username <user> --password <pass>
  

Cookie の値を決して捏造したり、推測したりしないでください。パスワードがコマンドラインを通らないように、login よりも auth set または環境変数を優先してください。認証情報がなく、取得もできない場合は、処理を中止して人間に確認してください。認証なしでは先に進めません。これらの操作では実際のアカウントにアクセスするため、そのログインは共有され、レート制限の対象となるリソースです。過度にアクセスしないでください。

出力形式を利用側に合わせて選択する

既定の json は、1 件の結果を人間が読む用途に向けて整形されています。自分やパイプラインで解析する場合は、--format を使って適切な形式を選んでください。

形式	フラグ	用途
JSON（整形済み）	(既定)	単一オブジェクトまたは少量の結果を確認する場合
JSONL	--format jsonl	大量の結果や複数ページの結果。1 行に 1 レコードで、追記やストリーム処理に適しています
CSV	--format csv	スプレッドシートや簡単な表形式の分析（ネストされたフィールドはセル内で JSON としてエンコードされます）
SQLite	--format sqlite --db out.db	クエリ可能なデータセットを作成する場合。行は tweets／users テーブルに保存され、概要は標準エラー出力に表示されます

コンパクトな 1 行の JSON には --plain を追加してください。標準出力をリダイレクトすればファイルに保存できます。例：… --format jsonl > tweets.jsonl。

コマンド

# Profile (by @handle or numeric id)
python3 scripts/xfetch.py user @elonmusk

# A user's tweets (--replies for replies, --media for media-only)
python3 scripts/xfetch.py tweets @elonmusk -n 50
python3 scripts/xfetch.py tweets @elonmusk --replies --all --format jsonl > timeline.jsonl

# A user's liked tweets
python3 scripts/xfetch.py likes @handle -n 40

# Single tweet, and a tweet with its replies (thread)
python3 scripts/xfetch.py tweet https://x.com/user/status/1234567890
python3 scripts/xfetch.py thread 1234567890

# Search (--type top|latest|media)
python3 scripts/xfetch.py search "AI agents" -n 100 --type latest
python3 scripts/xfetch.py search "from:openai since:2024-01-01" --all --format csv > openai.csv

# Followers / following, paginated into a SQLite dataset
python3 scripts/xfetch.py followers @handle --all --format sqlite --db network.db
python3 scripts/xfetch.py following @handle -n 100

# Your own timelines (uses the logged-in account)
python3 scripts/xfetch.py home              # "For You"
python3 scripts/xfetch.py home --following  # chronological
python3 scripts/xfetch.py bookmarks -n 50

search は X の高度な演算子（from:、to:、since:、until:、filter:、min_faves: など）に対応しています。引用符で囲んだクエリ内に指定してください。すべてのフラグと各コマンドが返すフィールドの詳細については、references/commands.md を参照してください。

この CLI を小規模に保つため、DM、リスト、トレンドはコマンドとして公開されていませんが、twikit はこれらをサポートしています（get_dm_history、get_list_tweets、get_trends）。必要な場合は、既存のパターンに従って scripts/xfetch.py にコマンドを追加してください。

ページネーションとレート制限

一覧表示コマンド（tweets、search、followers、following、likes、home、bookmarks）では、これらのフラグを共通で使用できます。デフォルトでは1ページのみ取得し、必要に応じて追加のページを取得します。

-n 40            # results per page
--all            # every page until exhausted
--max-pages 10   # cap the pages
--cursor <c>     # start from a specific pagination cursor
--delay 1.5      # seconds between pages (default 1.0 — keep it >0 for --all)

残りのページがある場合、または取得が途中で中断されたり、レート制限されたりした場合、CLI は next_cursor=<value> を stderr に出力します。この値を取得し、--cursor で渡すと、最初から再取得するのではなく、取得が停止した位置から正確に再開できます。

X はアカウントごとにレート制限を設けており（エンドポイントごとに15分間で数百リクエスト程度）、このツールはユーザーの実アカウントを使用します。大量に取得する場合は、適切な --delay を設定してください。サンプルだけ必要な場合は --all より --max-pages を優先し、過度なスクレイピングによってアカウントがスロットリングされたり、フラグが付けられたりする可能性があることに注意してください。より負荷の高い作業では、--proxy http://user:pass@host:port でプロキシ経由にしてください。

失敗した場合

終了コードを確認し、stderr を読んで原因を特定してください。

• 終了コード 2／Not authenticated → 上記の認証フローを実行してください。
• 終了コード 64／使用方法エラー → コマンドライン自体に誤りがあります（不明なフラグ、不正な値など）。呼び出し方を修正してください。認証を再実行してはいけません。
• 終了コード 3／レート制限 → stderr に rate_limit_reset=<epoch> が出力されます。その時刻まで待ち、--delay を増やし、stderr に出力された next_cursor= の値から再開してください。
• GraphQL エラーや解析エラーを伴う終了コード 1 が、突然すべてのユーザーで発生した場合 → X がサイトを変更した可能性があります。twikit をアップグレード（pip install -U twikit）して、再試行してください。
• 取得中のタイムアウト／ネットワークエラー → 最初から再取得するのではなく、stderr の next_cursor= の行にある値から再開してください。
• 結果が空の場合 → アカウントが非公開である（ログイン中のアカウントから見える内容しか表示されません）、凍結されている、またはハンドルが間違っている可能性があります。

対象範囲と適切な利用に関する注意事項

このツールが読み取るのは公開データと、ログイン中のアカウントが閲覧できるデータ（自身のホーム、ブックマーク、いいね）です。投稿、いいね、フォロー、その他の変更は行いません。設計上、読み取り専用です。ユーザー自身のセッションを使用するため、X の利用規約とレート制限を遵守する責任はユーザーにあります。正当な目的（研究、個人的なアーカイブ、ユーザーに閲覧する権利のあるアカウントのモニタリングなど）に使用してください。嫌がらせ、大規模監視、ブロックの回避には使用しないでください。セッション Cookie は ~/.config/xfetch/ に保存されます。auth clear で削除できます。