xurl — Agent Skill Reference

xurl は X API 用の CLI ツールです。ショートカットコマンド (人間・エージェント向けのワンライナー) と 生の curl スタイル の両方で任意の v2 エンドポイントにアクセスできます。すべてのコマンドは JSON を stdout に返します。

---

インストール

Homebrew (macOS)

brew install --cask xdevplatform/tap/xurl

npm

npm install -g @xdevplatform/xurl

シェルスクリプト

curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash

~/.local/bin にインストールされます。PATH に含まれていない場合は、スクリプトが追加すべき内容を教えてくれます。

Go

go install github.com/xdevplatform/xurl@latest

---

前提条件

このスキルには xurl CLI ユーティリティが必要です: https://github.com/xdevplatform/xurl

コマンドを使用する前に認証を済ませる必要があります。xurl auth status を実行して確認してください。

シークレット安全性 (必須)

• ~/.xurl (またはそのコピー) を読み込んだり、印刷したり、解析したり、要約したり、LLM コンテキストにアップロードしたり送信したりしないでください。
• ユーザーに認証情報・トークンをチャットに貼り付けるよう要求しないでください。
• ユーザーは自分のマシンで手動で ~/.xurl に必要なシークレットを入力する必要があります。
• エージェント/LLM セッション内でインラインシークレットを含む認証コマンドを推奨したり実行したりしないでください。
• CLI シークレットオプションをエージェントセッション内で使用すると認証情報がリークする可能性があることを警告してください (プロンプト/コンテキスト、ログ、シェル履歴)。
• エージェント/LLM セッション内では --verbose / -v を使用しないでください。機密ヘッダ/トークンが出力に露出する可能性があります。
• エージェントコマンドで絶対に使用してはいけない機密フラグ: --bearer-token, --consumer-key, --consumer-secret, --access-token, --token-secret, --client-id, --client-secret
• 認証情報を含む少なくとも 1 つのアプリが既に登録されているかどうかを確認するには、xurl auth status を実行してください。

アプリの登録 (推奨)

アプリ認証情報の登録はユーザーがエージェント/LLM セッション外で手動で実行する必要があります。 認証情報が登録されたら、以下で認証してください:

xurl auth oauth2

複数の事前設定済みアプリの場合、それらを切り替えます:

xurl auth default prod-app          # デフォルトアプリを設定
xurl auth default prod-app alice    # デフォルトアプリ + ユーザーを設定
xurl --app dev-app /2/users/me      # 1 回限りのオーバーライド

その他の認証方法

インラインシークレットフラグを含む例は意図的に省略されています。OAuth1 またはアプリのみ認証が必要な場合、ユーザーはエージェント/LLM コンテキスト外でそれらのコマンドを手動で実行する必要があります。

トークンは ~/.xurl に YAML 形式で保存されます。各アプリは独自の分離されたトークンを持ちます。このファイルをエージェント/LLM を通じて読み込まないでください。認証後、以下のすべてのコマンドは自動的に正しい Authorization ヘッダーを含めます。

---

クイックリファレンス

アクション	コマンド
投稿	xurl post "Hello world!"
返信	xurl reply POST_ID "Nice post!"
引用	xurl quote POST_ID "My take"
投稿を削除	xurl delete POST_ID
投稿を読む	xurl read POST_ID
投稿を検索	xurl search "QUERY" -n 10
自分は誰か	xurl whoami
ユーザーを検索	xurl user @handle
ホームタイムライン	xurl timeline -n 20
メンション	xurl mentions -n 10
いいね	xurl like POST_ID
いいねを取り消す	xurl unlike POST_ID
リポスト	xurl repost POST_ID
リポストを取り消す	xurl unrepost POST_ID
ブックマーク	xurl bookmark POST_ID
ブックマークを削除	xurl unbookmark POST_ID
ブックマークを一覧表示	xurl bookmarks -n 10
いいねを一覧表示	xurl likes -n 10
フォロー	xurl follow @handle
フォロー解除	xurl unfollow @handle
フォロー中を一覧表示	xurl following -n 20
フォロワーを一覧表示	xurl followers -n 20
ブロック	xurl block @handle
ブロック解除	xurl unblock @handle
ミュート	xurl mute @handle
ミュート解除	xurl unmute @handle
DM を送信	xurl dm @handle "message"
DM を一覧表示	xurl dms -n 10
メディアをアップロード	xurl media upload path/to/file.mp4
メディア状態	xurl media status MEDIA_ID
アプリ管理
アプリを登録	手動、エージェント外 (シークレットはエージェント経由で渡さない)
アプリを一覧表示	xurl auth apps list
アプリ認証情報を更新	手動、エージェント外 (シークレットはエージェント経由で渡さない)
アプリを削除	xurl auth apps remove NAME
デフォルトを設定 (対話的)	xurl auth default
デフォルトを設定 (コマンド)	xurl auth default APP_NAME [USERNAME]
リクエストごとにアプリを使用	xurl --app NAME /2/users/me
認証ステータス	xurl auth status

投稿 ID vs URL: 上記で POST_ID が表示される場所ならどこでも、完全な投稿 URL を貼り付けることができます (例: https://x.com/user/status/1234567890) — xurl が自動的に ID を抽出します。

ユーザー名: 先頭の @ はオプションです。@elonmusk と elonmusk の両方が機能します。

---

コマンド詳細

投稿

# シンプルな投稿
xurl post "Hello world!"

# メディア付き投稿 (先にアップロード、その後アタッチ)
xurl media upload photo.jpg          # → レスポンスから media_id を確認
xurl post "Check this out" --media-id MEDIA_ID

# 複数のメディア
xurl post "Thread pics" --media-id 111 --media-id 222

# 投稿に返信 (ID または URL で)
xurl reply 1234567890 "Great point!"
xurl reply https://x.com/user/status/1234567890 "Agreed!"

# メディア付き返信
xurl reply 1234567890 "Look at this" --media-id MEDIA_ID

# 投稿を引用
xurl quote 1234567890 "Adding my thoughts"

# 自分の投稿を削除
xurl delete 1234567890

読む

# 単一の投稿を読む (著者、テキスト、メトリクス、エンティティを返す)
xurl read 1234567890
xurl read https://x.com/user/status/1234567890

# 最近の投稿を検索 (デフォルト 10 件の結果)
xurl search "golang"
xurl search "from:elonmusk" -n 20
xurl search "#buildinpublic lang:en" -n 15

ユーザー情報

# 自分のプロフィール
xurl whoami

# 任意のユーザーを検索
xurl user elonmusk
xurl user @XDevelopers

タイムライン & メンション

# ホームタイムライン (逆時系列)
xurl timeline
xurl timeline -n 25

# 自分のメンション
xurl mentions
xurl mentions -n 20

エンゲージメント

# いいね / いいね取り消し
xurl like 1234567890
xurl unlike 1234567890

# リポスト / 取り消し
xurl repost 1234567890
xurl unrepost 1234567890

# ブックマーク / 削除
xurl bookmark 1234567890
xurl unbookmark 1234567890

# ブックマークといいねを一覧表示
xurl bookmarks -n 20
xurl likes -n 20

ソーシャルグラフ

# フォロー / フォロー解除
xurl follow @XDevelopers
xurl unfollow @XDevelopers

# フォロー中とフォロワーを一覧表示
xurl following -n 50
xurl followers -n 50

# 別のユーザーのフォロー中/フォロワーを一覧表示
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20

# ブロック / ブロック解除
xurl block @spammer
xurl unblock @spammer

# ミュート / ミュート解除
xurl mute @annoying
xurl unmute @annoying

ダイレクトメッセージ

# DM を送信
xurl dm @someuser "Hey, saw your post!"

# 最近の DM イベントを一覧表示
xurl dms
xurl dms -n 25

メディアアップロード

# ファイルをアップロード (画像/ビデオのタイプを自動検出)
xurl media upload photo.jpg
xurl media upload video.mp4

# タイプとカテゴリを明示的に指定
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg

# 処理ステータスを確認 (ビデオはサーバー側の処理が必要)
xurl media status MEDIA_ID
xurl media status --wait MEDIA_ID    # 完了までポーリング

# 完全なワークフロー: アップロード後に投稿
xurl media upload meme.png           # レスポンスに media id が含まれる
xurl post "lol" --media-id MEDIA_ID

---

グローバルフラグ

これらのフラグはすべてのコマンドで機能します:

フラグ	短形	説明
--app		このリクエストに登録済みの特定のアプリを使用 (デフォルトをオーバーライド)
--auth		認証タイプを強制: oauth1, oauth2, または app
--username	-u	使用する OAuth2 アカウント (複数ある場合)
--verbose	-v	エージェント/LLM セッションで禁止 (認証ヘッダ/トークンがリークする可能性)
--trace	-t	X-B3-Flags: 1 トレースヘッダを追加

---

生の API アクセス

ショートカットコマンドは最も一般的な操作をカバーしています。その他のケースについては、xurl の生の curl スタイルモードを使用してください — 任意の X API v2 エンドポイントで機能します:

# GET リクエスト (デフォルト)
xurl /2/users/me

# JSON ボディを使った POST
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'

# PUT, PATCH, DELETE
xurl -X DELETE /2/tweets/1234567890

# カスタムヘッダ
xurl -H "Content-Type: application/json" /2/some/endpoint

# ストリーミングモードを強制
xurl -s /2/tweets/search/stream

# 完全な URL も機能
xurl https://api.x.com/2/users/me

---

ストリーミング

ストリーミングエンドポイントは自動検出されます。既知のストリーミングエンドポイントは以下の通りです:

• /2/tweets/search/stream
• /2/tweets/sample/stream
• /2/tweets/sample10/stream

-s でストリーミングを強制できます:

xurl -s /2/some/endpoint

---

出力形式

すべてのコマンドは stdout に JSON を返します。構文ハイライト付きで整形印刷されます。出力構造は X API v2 レスポンス形式に一致します。典型的なレスポンスは以下のようになります:

{
  "data": {
    "id": "1234567890",
    "text": "Hello world!"
  }
}

エラーも JSON として返されます:

{
  "errors": [
    {
      "message": "Not authorized",
      "code": 403
    }
  ]
}

---

よくあるワークフロー

画像付きで投稿

# 1. 画像をアップロード
xurl media upload photo.jpg
# 2. レスポンスから media_id をコピー、その後投稿
xurl post "Check out this photo!" --media-id MEDIA_ID

スレッドに返信

# 1. 投稿を読んでコンテキストを理解
xurl read https://x.com/user/status/1234567890
# 2. 返信
xurl reply 1234567890 "Here are my thoughts..."

検索とエンゲージ

# 1. 関連する投稿を検索
xurl search "topic of interest" -n 10
# 2. 興味深いものにいいね
xurl like POST_ID_FROM_RESULTS
# 3. それに返信
xurl reply POST_ID_FROM_RESULTS "Great point!"

アクティビティを確認

# 自分が誰かを確認
xurl whoami
# メンションを確認
xurl mentions -n 20
# タイムラインを確認
xurl timeline -n 20

複数のアプリを設定

# アプリ認証情報は既にエージェント/LLM コンテキスト外で手動で設定されていなければなりません。
# 各事前設定済みアプリでユーザーを認証
xurl auth default prod
xurl auth oauth2                       # prod アプリで認証

xurl auth default staging
xurl auth oauth2                       # staging アプリで認証

# それらを切り替え
xurl auth default prod alice           # prod アプリ、alice ユーザー
xurl --app staging /2/users/me         # staging に対する 1 回限りのリクエスト

---

エラー処理

• エラー時は 0 以外の終了コード。
• API エラーは JSON として stdout に印刷されます (それでもパースできるように)。
• 認証エラーは xurl auth oauth2 の再実行またはトークンの確認を提案します。
• ユーザー ID が必要なコマンド (いいね、リポスト、ブックマーク、フォローなど) の場合、xurl は自動的に /2/users/me 経由でそれを取得します。失敗した場合は認証エラーが表示されます。

---

注釈

• レート制限: X API はエンドポイントごとにレート制限を適用します。429 エラーが出た場合は待機して再試行してください。書き込みエンドポイント (投稿、返信、いいね、リポスト) は読み込みエンドポイントよりも厳しい制限があります。
• スコープ: OAuth 2.0 トークンは広いスコープで要求されます。特定のアクションで 403 が出た場合、トークンに必要なスコープがない可能性があります — xurl auth oauth2 を再実行して新しいトークンを取得してください。
• トークン更新: OAuth 2.0 トークンは期限切れ時に自動更新されます。手動介入は不要です。
• 複数アプリ: 各アプリは独自の分離された認証情報とトークンを持ちます。認証情報を手動でエージェント/LLM コンテキスト外で設定してから、xurl auth default または --app で切り替えてください。
• 複数アカウント: アプリごとに複数の OAuth 2.0 アカウントを認証でき、--username / -u で切り替えるか、xurl auth default APP USER でデフォルトを設定できます。
• デフォルトユーザー: -u フラグがない場合、xurl はアクティブなアプリのデフォルトユーザーを使用します (xurl auth default で設定)。デフォルトユーザーが設定されていない場合は、最初の利用可能なトークンを使用します。
• トークンストレージ: ~/.xurl は YAML です。各アプリは独自の認証情報とトークンを保存します。このファイルを読み込んだり LLM コンテキストに送ったりしないでください。