xurl

xurl — 公式 CLI を介した X（Twitter）API

xurl は、X API 用の X 開発者プラットフォーム公式 CLI です。一般的な操作のショートカットコマンドに加え、あらゆる v2 エンドポイントに対する curl 形式の直接アクセスをサポートしています。すべてのコマンドは JSON を標準出力に返します。

次の用途にこのスキルを使用します。

• 投稿、返信、引用、投稿の削除
• 投稿の検索（操作可能な ID を含む実際の投稿 JSON）と、タイムライン／メンションの閲覧
• いいね、リポスト、ブックマーク
• フォロー、フォロー解除、ブロック、ミュート
• ダイレクトメッセージ
• メディアのアップロード（画像と動画）
• あらゆる X API v2 エンドポイントへの直接アクセス
• 複数アプリ／複数アカウントのワークフロー

このスキルは、旧 xitter スキル（サードパーティ製の Python CLI をラップしていたもの）に代わるものです。xurl は X 開発者プラットフォームチームが保守しており、自動更新に対応した OAuth 2.0 PKCE をサポートし、より広範な API を利用できます。

---

シークレットの安全性（必須）

エージェント／LLM セッション内で操作する際の重要なルール：

• ~/.xurl を読み取ったり、表示、解析、要約、アップロード、送信したりすることは絶対にしないでください。
• ユーザーに認証情報／トークンをチャットに貼り付けるよう求めてはいけません。
• ユーザーは自身のマシンで、手動で ~/.xurl にシークレットを入力する必要があります。Docker では、Hermes のツールサブプロセスから見える ~ に入力する必要があります。下記の Docker に関する注意を参照してください。
• エージェントセッション内で、インラインのシークレットを含む認証コマンドを推奨または実行してはいけません。
• エージェントセッション内で --verbose／-v を使用してはいけません。認証ヘッダー／トークンが露出する可能性があります。
• 認証情報が存在することを確認する場合は、xurl auth status のみを使用してください。

エージェントのコマンドで禁止されているフラグ（インラインのシークレットを受け付けます）： --bearer-token、--consumer-key、--consumer-secret、--access-token、--token-secret、--client-id、--client-secret

アプリの認証情報の登録とローテーションは、エージェントセッションの外で、ユーザーが手動で行う必要があります。認証情報の登録後、ユーザーはエージェントセッションの外で xurl auth oauth2 を使用して認証します。トークンは YAML 形式で ~/.xurl に保存されます。アプリごとにトークンは分離されています。OAuth 2.0 トークンは自動更新されます。

---

インストール

方法を1つ選んでください。Linux では、シェルスクリプトまたは go install が最も簡単です。

# Shell script (installs to ~/.local/bin, no sudo, works on Linux + macOS)
curl -fsSL https://raw.githubusercontent.com/xdevplatform/xurl/main/install.sh | bash

# Homebrew (macOS)
brew install --cask xdevplatform/tap/xurl

# npm
npm install -g @xdevplatform/xurl

# Go
go install github.com/xdevplatform/xurl@latest

確認：

xurl --help
xurl auth status

xurl がインストールされていても、auth status にアプリやトークンが表示されない場合、ユーザーが認証を手動で完了する必要があります。次のセクションを参照してください。

---

ユーザーによる初回セットアップ（一度だけ。エージェントの外で実行します）

これらの手順は、シークレットを貼り付ける必要があるため、エージェントではなくユーザーが直接実行してください。このブロックをユーザーに案内し、代わりに実行しないでください。

1. https://developer.x.com/en/portal/dashboard でアプリを作成するか、開きます

2. リダイレクト URI を http://localhost:8080/callback に設定します

3. アプリの Client ID と Client Secret をコピーします

4. アプリをローカルに登録します（ユーザーが実行）：

   xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
   

5. 認証します（トークンをアプリに紐付けるには --app を指定します）：

   xurl auth oauth2 --app my-app
   

   （OAuth 2.0 PKCE フロー用のブラウザーが開きます。）

   X が /2/users/me の呼び出し後に UsernameNotFound エラーまたは 403 を返す場合は、ハンドルを明示的に指定してください（xurl v1.1.0 以降）：

   xurl auth oauth2 --app my-app YOUR_USERNAME
   

   これにより、トークンがハンドルに紐付けられ、失敗する /2/users/me の呼び出しがスキップされます。

6. すべてのコマンドでアプリが使われるよう、デフォルトに設定します：

   xurl auth default my-app
   

7. 確認します：

   xurl auth status
   xurl whoami
   

これ以降、エージェントは追加のセットアップなしで、以下の任意のコマンドを使用できます。OAuth 2.0 トークンは自動的に更新されます。

よくある落とし穴： xurl auth oauth2 で --app my-app を省略すると、OAuth トークンは組み込みの default アプリプロファイルに保存されます。このプロファイルには client-id も client-secret もありません。OAuth フローが成功したように見えても、コマンドは認証エラーで失敗します。この問題が起きた場合は、xurl auth oauth2 --app my-app と xurl auth default my-app を再実行してください。

Docker の HOME に関する落とし穴： 公式の Hermes Docker レイアウトでは、/opt/data が HERMES_HOME ですが、Hermes のツールサブプロセスは HOME として /opt/data/home を使用します。つまり、Hermes が実行する xurl コマンドでは、~/.xurl は /opt/data/.xurl ではなく /opt/data/home/.xurl に解決されます。ユーザーのセットアップは同じ HOME を使って実行してください：

HOME=/opt/data/home xurl auth apps add my-app --client-id YOUR_CLIENT_ID --client-secret YOUR_CLIENT_SECRET
HOME=/opt/data/home xurl auth oauth2 --app my-app YOUR_USERNAME
HOME=/opt/data/home xurl auth default my-app YOUR_USERNAME
HOME=/opt/data/home xurl auth status

HOME=/opt/data xurl auth status は成功する一方で、HOME=/opt/data/home xurl auth status ではアプリやトークンが表示されない場合、Hermes のツール呼び出しから認証情報を参照できません。

---

クイックリファレンス

操作	コマンド
投稿	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 APP_NAME [USERNAME]
リクエストごとにアプリを指定	xurl --app NAME /2/users/me
認証ステータス	xurl auth status

注：

• POST_ID には完全な URL も指定できます（例：https://x.com/user/status/1234567890）。xurl が ID を抽出します。
• ユーザー名は、先頭の @ の有無にかかわらず使用できます。

---

コマンドの詳細

投稿

xurl post "Hello world!"
xurl post "Check this out" --media-id MEDIA_ID
xurl post "Thread pics" --media-id 111 --media-id 222

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 search は、認証済みアカウントとして X のインデックスを検索し、生の投稿オブジェクト（ID、投稿者、全文）を返します。そのため、結果に対してすぐにアクション（返信、いいね、リポスト、引用）を行えます。トピックの要約ではなく、実際の投稿が必要な場合に使用してください。

xurl read 1234567890
xurl read https://x.com/user/status/1234567890

xurl search "golang"
xurl search "from:elonmusk" -n 20
xurl search "#buildinpublic lang:en" -n 15

X Articles には、read ショートカットではなく、生の API モードを使用してください。xurl read は投稿 ID または投稿 URL を想定しているため、/2/tweets/... エンドポイントの前に read を付けないでください。article ツイートフィールドをリクエストし、JSON レスポンスの data.article.plain_text を取り込んでください。

xurl --app APP_NAME '/2/tweets/2057909493250539891?expansions=author_id,attachments.media_keys,referenced_tweets.id&tweet.fields=created_at,lang,public_metrics,context_annotations,entities,possibly_sensitive,conversation_id,in_reply_to_user_id,referenced_tweets,article'

ユーザー、タイムライン、メンション

xurl whoami
xurl user elonmusk
xurl user @XDevelopers

xurl timeline -n 25
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

# Another user's graph
xurl following --of elonmusk -n 20
xurl followers --of elonmusk -n 20

xurl block @spammer
xurl unblock @spammer
xurl mute @annoying
xurl unmute @annoying

ダイレクトメッセージ

xurl dm @someuser "Hey, saw your post!"
xurl dms -n 25

メディアのアップロード

# Auto-detect type
xurl media upload photo.jpg
xurl media upload video.mp4

# Explicit type/category
xurl media upload --media-type image/jpeg --category tweet_image photo.jpg

# Videos need server-side processing — check status (or poll)
xurl media status MEDIA_ID
xurl media status --wait MEDIA_ID

# Full workflow
xurl media upload meme.png                  # returns media id
xurl post "lol" --media-id MEDIA_ID

---

生の API アクセス

ショートカットでは一般的な操作をカバーしています。それ以外の場合は、任意の X API v2 エンドポイントに対して、生の curl 形式のモードを使用してください。

# GET
xurl /2/users/me

# POST with JSON body
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'

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

# Custom headers
xurl -H "Content-Type: application/json" /2/some/endpoint

# Force streaming
xurl -s /2/tweets/search/stream

# Full URLs also work
xurl https://api.x.com/2/users/me

---

グローバルフラグ

フラグ	短縮形	説明
--app		特定の登録済みアプリを使用します（デフォルトを上書き）
--auth		認証タイプを強制します：oauth1、oauth2、または app
--username	-u	使用する OAuth2 アカウント（複数ある場合）
--verbose	-v	エージェントセッションでは禁止 — 認証ヘッダーが漏えいします
--trace	-t	トレースヘッダー X-B3-Flags: 1 を追加します

---

ストリーミング

ストリーミングエンドポイントは自動検出されます。既知のものは次のとおりです。

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

-s を指定すると、任意のエンドポイントでストリーミングを強制できます。

---

出力形式

すべてのコマンドは JSON を stdout に返します。構造は X API v2 に準拠しています。

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

エラーも JSON 形式です。

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

---

一般的なワークフロー

画像付きで投稿する

xurl media upload photo.jpg
xurl post "Check out this photo!" --media-id MEDIA_ID

会話に返信する

xurl read https://x.com/user/status/1234567890
xurl reply 1234567890 "Here are my thoughts..."

検索してエンゲージする

xurl search "topic of interest" -n 10
xurl like POST_ID_FROM_RESULTS
xurl reply POST_ID_FROM_RESULTS "Great point!"

自分のアクティビティを確認する

xurl whoami
xurl mentions -n 20
xurl timeline -n 20

複数のアプリ（認証情報は手動で事前設定）

xurl auth default prod alice               # prod app, alice user
xurl --app staging /2/users/me             # one-off against staging

---

エラー処理

• エラーが発生すると、終了コードは 0 以外になります。
• API エラーも JSON として stdout に出力されるため、解析できます。
• 認証エラーの場合 → ユーザーに、エージェントセッションの外で xurl auth oauth2 を再実行してもらってください。
• 呼び出し元のユーザー ID を必要とするコマンド（いいね、リポスト、ブックマーク、フォローなど）は、/2/users/me を使って自動的に取得します。そこで認証に失敗すると、認証エラーとして通知されます。

---

エージェントのワークフロー

1. 前提条件を確認します：xurl --help と xurl auth status。
2. xurl search を使う前に、意図を確認します。実際の投稿オブジェクト、認証済みアカウントのコンテキストが必要な場合や、X への書き込みアクションにつながる場合に使用してください。トピックの要約だけでなく、エンゲージできる投稿をユーザーが求めている場合に適しています。
3. デフォルトアプリに認証情報があることを確認します。 auth status の出力を解析してください。デフォルトアプリには ▸ が付いています。デフォルトアプリの oauth2: (none) が表示されていても、別のアプリに有効な oauth2 ユーザーがある場合は、xurl auth default <that-app> を実行して修正するようユーザーに伝えてください。これは最もよくある設定ミスです。ユーザーが独自の名前でアプリを追加したものの、デフォルトに設定しなかったため、xurl は認証情報のない default プロファイルを使い続けています。
4. 認証情報がまったくない場合は停止し、「One-Time User Setup」セクションを案内してください。アプリの登録やシークレットの受け渡しを試みてはいけません。
5. xurl whoami、xurl user @handle、xurl search ... -n 3 など、低コストな読み取りから始め、アクセス可能であることを確認します。
6. 書き込みアクション（投稿、返信、いいね、リポスト、DM、フォロー、ブロック、削除）の前に、対象の投稿またはユーザーと、ユーザーの意図を確認します。
7. X の状態を変更するアクションが実行されたことを証明できるのは、xurl コマンドの出力（または生の X API レスポンス）だけです。検索結果、要約、以前のコンテキストなど、ほかの情報を根拠に書き込みが完了したと報告してはいけません。
8. JSON 出力をそのまま使用してください。すべてのレスポンスはすでに構造化されています。
9. ~/.xurl の内容を会話に貼り付けてはいけません。

---

トラブルシューティング

症状	原因	対処方法
OAuth フローの成功後に認証エラーが発生する	トークンが名前付きアプリではなく（クライアント ID／シークレットのない）default アプリに保存されている	xurl auth oauth2 --app my-app を実行してから、xurl auth default my-app を実行します
OAuth 中に unauthorized_client が発生する	X ダッシュボードでアプリの種類が「Native App」に設定されている	User Authentication Settings で「Web app, automated app or bot」に変更します
OAuth の直後に /2/users/me で UsernameNotFound または 403 が発生する	X が /2/users/me からユーザー名を安定して返さない	xurl auth oauth2 --app my-app YOUR_USERNAME を再実行して、ハンドルを明示的に渡します（xurl v1.1.0 以降）
すべてのリクエストで 401 が発生する	トークンの有効期限が切れているか、デフォルトアプリが正しくない	xurl auth status を確認し、▸ が oauth2 トークンのあるアプリを指していることを確認します
client-forbidden ／ client-not-enrolled が発生する	X プラットフォームの登録に関する問題	Dashboard → Apps → Manage →「Pay-per-use」パッケージに移動 → Production environment
CreditsDepleted が発生する	X API の残高が $0	Developer Console → Billing でクレジットを購入します（最低 $5）
画像のアップロード時に media processing failed が発生する	デフォルトのカテゴリが amplify_video になっている	--category tweet_image --media-type image/png を追加します
X ダッシュボードに「Client Secret」が 2 つ表示される	UI のバグです。最初の値は実際には Client ID です	「Keys and tokens」ページで確認します。ID の末尾は MTpjaQ です

---

注意事項

• レート制限： X ではエンドポイントごとにレート制限が適用されます。429 が返された場合は、待ってから再試行します。書き込みエンドポイント（投稿、返信、いいね、リポスト）の制限は、読み取りより厳しく設定されています。
• スコープ： OAuth 2.0 トークンは広範なスコープを使用します。特定の操作で 403 が発生する場合、通常はトークンにスコープが不足しています。ユーザーに xurl auth oauth2 を再実行してもらいます。
• トークンの更新： OAuth 2.0 トークンは自動的に更新されます。特別な対応は不要です。
• 複数のアプリ： アプリごとに認証情報とトークンが分離されています。xurl auth default または --app で切り替えます。
• 1 つのアプリで複数のアカウントを使用する場合： -u / --username で選択するか、xurl auth default APP USER でデフォルトを設定します。
• トークンの保存先： ~/.xurl は YAML 形式です。Docker では Hermes のサブプロセスの HOME（公式イメージでは /opt/data/home）を使用し、トークンが /opt/data/home/.xurl に保存されるようにします。このファイルを読み取ったり、LLM のコンテキストに送信したりしないでください。
• 費用： X API の利用には、実用的な規模での使用に対して通常料金が発生します。多くの問題はコードではなく、プランや権限に起因します。

---

クレジット

• 上流の CLI： https://github.com/xdevplatform/xurl （X developer platform team、Chris Park ほか）
• 上流のエージェントスキル： https://github.com/openclaw/openclaw/blob/main/skills/xurl/SKILL.md
• Hermes への適用：Hermes のスキル規約に合わせて再フォーマット。安全対策のガードレールは原文のまま維持しています。