xurl

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

xurl — Agent Skill Reference

xurl — Agent技能参考

xurl

is a CLI tool for the X API. It supports both shortcut commands (human/agent‑friendly one‑liners) and raw curl‑style access to any v2 endpoint. All commands return JSON to stdout.

xurl

是一款面向X API的CLI工具。它同时支持快捷命令（适合人类/Agent使用的单行命令）和原生curl风格的方式访问任何v2端点。所有命令均会向标准输出返回JSON格式结果。

Installation

安装

Homebrew (macOS)

Homebrew（macOS）

bash

brew install --cask xdevplatform/tap/xurl

bash

brew install --cask xdevplatform/tap/xurl

npm

bash

npm install -g @xdevplatform/xurl

bash

npm install -g @xdevplatform/xurl

Shell script

Shell脚本

bash

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

Installs to

~/.local/bin

. If it's not in your PATH, the script will tell you what to add.

bash

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

安装路径为

~/.local/bin

。如果该路径不在你的PATH中，脚本会提示你需要添加的内容。

Go

bash

go install github.com/xdevplatform/xurl@latest

bash

go install github.com/xdevplatform/xurl@latest

Prerequisites

前提条件

This skill requires the

xurl

CLI utility: https://github.com/xdevplatform/xurl.

Before using any command you must be authenticated. Run

xurl auth status

to check.

使用此技能需要

xurl

CLI工具：https://github.com/xdevplatform/xurl。

在使用任何命令前，你必须完成身份验证。运行

xurl auth status

检查验证状态。

First-Time Setup

首次设置

xurl auth status

shows no apps registered, walk the user through these three steps before doing anything else. Each step requires the user to act manually outside the agent session — never pass credentials inline through the agent.

Step 1 — Register your app (user runs this manually, outside agent/LLM context):

bash

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

The user must obtain

CLIENT_ID

and

CLIENT_SECRET

from the X developer portal.

Step 2 — Set it as the default app:

bash

xurl auth default my-app

Step 3 — Authenticate via OAuth 2.0:

bash

xurl auth oauth2

This opens a browser for the OAuth flow. After completing it, tokens are saved to

~/.xurl

and all subsequent commands will use them automatically.

Confirm setup is complete by running

xurl auth status

and

xurl whoami

before proceeding with the user's actual task.

如果

xurl auth status

显示未注册任何应用，请在执行其他操作前引导用户完成以下三个步骤**。每个步骤都需要用户在Agent会话外手动操作——切勿通过Agent传递凭据。

步骤1 — 注册你的应用（用户需在Agent/LLM上下文外手动执行）：

bash

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

用户必须从X开发者门户获取

CLIENT_ID

和

CLIENT_SECRET

。

步骤2 — 将其设置为默认应用：

bash

xurl auth default my-app

步骤3 — 通过OAuth 2.0进行身份验证：

bash

xurl auth oauth2

此命令会打开浏览器启动OAuth流程。完成后，令牌将保存到

~/.xurl

，后续所有命令都会自动使用这些令牌。

在继续执行用户的实际任务前，通过运行

xurl auth status

和

xurl whoami

确认设置已完成。

Secret Safety (Mandatory)

密钥安全（强制要求）

Never read, print, parse, summarize, upload, or send
```
~/.xurl
```
(or copies of it) to the LLM context.
Never ask the user to paste credentials/tokens into chat.
The user must fill
```
~/.xurl
```
with required secrets manually on their own machine.
Do not recommend or execute auth commands with inline secrets in agent/LLM sessions.
Warn that using CLI secret options in agent sessions can leak credentials (prompt/context, logs, shell history).
Never use
```
--verbose
```
/
```
-v
```
in agent/LLM sessions; it can expose sensitive headers/tokens in output.

Sensitive flags that must never be used in agent commands:

--bearer-token

--consumer-key

--consumer-secret

--access-token

--token-secret

--client-id

--client-secret

To verify whether at least one app with credentials is already registered, run:
```
xurl auth status
```
.

切勿读取、打印、解析、总结、上传或发送
```
~/.xurl
```
（或其副本）到LLM上下文。
切勿要求用户在聊天中粘贴凭据/令牌。
用户必须在自己的机器上手动向
```
~/.xurl
```
填充所需密钥。
切勿在Agent/LLM会话中推荐或执行包含内联密钥的认证命令。
警告用户：在Agent会话中使用CLI密钥选项可能会导致凭据泄露（提示/上下文、日志、Shell历史记录）。
切勿在Agent/LLM会话中使用
```
--verbose
```
/
```
-v
```
；它可能会在输出中暴露敏感的头部信息/令牌。

在Agent命令中绝对禁止使用的敏感标志：

--bearer-token

、

--consumer-key

、

--consumer-secret

、

--access-token

、

--token-secret

、

--client-id

、

--client-secret

。

要验证是否已注册至少一个带有凭据的应用，请运行：
```
xurl auth status
```
。

Register an app (recommended)

注册应用（推荐）

App credential registration must be done manually by the user outside the agent/LLM session. After credentials are registered, authenticate with:

bash

xurl auth oauth2

For multiple pre-configured apps, switch between them:

bash

xurl auth default prod-app          # set default app
xurl auth default prod-app alice    # set default app + user
xurl --app dev-app /2/users/me      # one-off override

应用凭据的注册必须由用户在Agent/LLM会话外手动完成。注册凭据后，通过以下命令进行身份验证：

bash

xurl auth oauth2

对于多个预配置的应用，可通过以下命令切换：

bash

xurl auth default prod-app          # 设置默认应用
xurl auth default prod-app alice    # 设置默认应用 + 用户
xurl --app dev-app /2/users/me      # 单次覆盖默认应用

Other auth methods

其他认证方式

Examples with inline secret flags are intentionally omitted. If OAuth1 or app-only auth is needed, the user must run those commands manually outside agent/LLM context.

If X does not return your username reliably through

/2/users/me

, pass an explicit handle to keep the token correctly associated:

bash

xurl auth oauth2 YOUR_USERNAME

Tokens are persisted to

~/.xurl

in YAML format. Each app has its own isolated tokens. Do not read this file through the agent/LLM. Once authenticated, every command below will auto‑attach the right

Authorization

header.

故意省略了包含内联密钥标志的示例。如果需要OAuth1或仅应用认证，用户必须在Agent/LLM上下文外手动运行这些命令。

如果X无法通过

/2/users/me

可靠地返回你的用户名，请传递明确的用户名以确保令牌关联正确：

bash

xurl auth oauth2 YOUR_USERNAME

令牌以YAML格式持久化存储在

~/.xurl

中。每个应用都有独立的令牌存储。切勿通过Agent/LLM读取此文件。完成认证后，以下所有命令都会自动附加正确的

Authorization

头部。

Clear Authentication

清除认证信息

bash

xurl auth clear --all                         # Remove all tokens across all apps
xurl auth clear --oauth1                      # Remove OAuth 1.0a tokens only
xurl auth clear --oauth2-username USERNAME    # Remove a specific OAuth 2.0 user token
xurl auth clear --bearer                      # Remove the bearer token only

bash

xurl auth clear --all                         # 删除所有应用的所有令牌
xurl auth clear --oauth1                      # 仅删除OAuth 1.0a令牌
xurl auth clear --oauth2-username USERNAME    # 删除特定OAuth 2.0用户的令牌
xurl auth clear --bearer                      # 仅删除Bearer令牌

Redirect URI Management

重定向URI管理

When working with multiple apps or custom callback URLs, you can inspect and update stored redirect URIs without touching credentials:

bash

undefined

当处理多个应用或自定义回调URL时，你可以检查和更新存储的重定向URI，而无需修改凭据：

bash

undefined

View effective redirect URI (shows env override vs stored vs built-in default)

查看有效重定向URI（显示环境变量覆盖值、存储值与内置默认值）

xurl auth apps redirect-uri get my-app

Store a per-app redirect URI (env var REDIRECT_URI overrides at runtime)

为应用存储重定向URI（运行时环境变量REDIRECT_URI会覆盖此值）

xurl auth apps redirect-uri set my-app http://localhost:8080/callback

Update app credentials without re-registering (no inline secrets in agent sessions)

更新应用凭据而无需重新注册（Agent会话中禁止使用内联密钥）

Run manually by the user outside agent/LLM context:

用户需在Agent/LLM上下文外手动执行：

xurl auth apps update my-app --client-id NEW_ID --client-secret NEW_SECRET

---

---

Quick Reference

快速参考

Action	Command
Post	`xurl post "Hello world!"`
Reply	`xurl reply POST_ID "Nice post!"`
Quote	`xurl quote POST_ID "My take"`
Delete a post	`xurl delete POST_ID`
Read a post	`xurl read POST_ID`
Search posts	`xurl search "QUERY" -n 10`
Who am I	`xurl whoami`
Look up a user	`xurl user @handle`
Home timeline	`xurl timeline -n 20`
Mentions	`xurl mentions -n 10`
Like	`xurl like POST_ID`
Unlike	`xurl unlike POST_ID`
Repost	`xurl repost POST_ID`
Undo repost	`xurl unrepost POST_ID`
Bookmark	`xurl bookmark POST_ID`
Remove bookmark	`xurl unbookmark POST_ID`
List bookmarks	`xurl bookmarks -n 10`
List likes	`xurl likes -n 10`
Follow	`xurl follow @handle`
Unfollow	`xurl unfollow @handle`
List following	`xurl following -n 20`
List followers	`xurl followers -n 20`
Block	`xurl block @handle`
Unblock	`xurl unblock @handle`
Mute	`xurl mute @handle`
Unmute	`xurl unmute @handle`
Send DM	`xurl dm @handle "message"`
List DMs	`xurl dms -n 10`
Upload media	`xurl media upload path/to/file.mp4`
Media status	`xurl media status MEDIA_ID`
Media status (wait)	`xurl media status --wait MEDIA_ID`
App Management
Register app	Manual, outside agent (do not pass secrets via agent)
List apps	`xurl auth apps list`
Update app creds	Manual, outside agent (do not pass secrets via agent)
View redirect URI	`xurl auth apps redirect-uri get APP_NAME`
Set redirect URI	`xurl auth apps redirect-uri set APP_NAME URL`
Remove app	`xurl auth apps remove NAME`
Set default (interactive)	`xurl auth default`
Set default (command)	`xurl auth default APP_NAME [USERNAME]`
Use app per-request	`xurl --app NAME /2/users/me`
Auth status	`xurl auth status`
Clear all tokens	`xurl auth clear --all`
Clear OAuth2 user token	`xurl auth clear --oauth2-username USERNAME`
Clear bearer token	`xurl auth clear --bearer`
Webhooks
Start local webhook	`xurl webhook start`
Webhook with custom port	`xurl webhook start -p 8081 -o events.log`

Post IDs vs URLs: Anywhere
POST_ID
appears above you can also paste a full post URL (e.g.
https://x.com/user/status/1234567890
) — xurl extracts the ID automatically.

Usernames: Leading
@
is optional.
@elonmusk
and
elonmusk
both work.

操作	命令
发布帖子	`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`
发送私信	`xurl dm @handle "message"`
查看私信列表	`xurl dms -n 10`
上传媒体	`xurl media upload path/to/file.mp4`
媒体状态检查	`xurl media status MEDIA_ID`
媒体状态检查（等待完成）	`xurl media status --wait MEDIA_ID`
应用管理
注册应用	手动操作，需在Agent外执行（切勿通过Agent传递密钥）
查看应用列表	`xurl auth apps list`
更新应用凭据	手动操作，需在Agent外执行（切勿通过Agent传递密钥）
查看重定向URI	`xurl auth apps redirect-uri get APP_NAME`
设置重定向URI	`xurl auth apps redirect-uri set APP_NAME URL`
删除应用	`xurl auth apps remove NAME`
设置默认应用（交互式）	`xurl auth default`
设置默认应用（命令式）	`xurl auth default APP_NAME [USERNAME]`
单次请求指定应用	`xurl --app NAME /2/users/me`
认证状态检查	`xurl auth status`
清除所有令牌	`xurl auth clear --all`
清除OAuth2用户令牌	`xurl auth clear --oauth2-username USERNAME`
清除Bearer令牌	`xurl auth clear --bearer`
Webhooks
启动本地Webhook服务器	`xurl webhook start`
自定义端口启动Webhook	`xurl webhook start -p 8081 -o events.log`

帖子ID与URL： 上述所有出现
POST_ID
的位置，你也可以粘贴完整的帖子URL（例如
https://x.com/user/status/1234567890
）——xurl会自动提取ID。

用户名： 开头的
@
是可选的。
@elonmusk
和
elonmusk
均可正常使用。

Command Details

命令详情

Posting

发布内容

bash

undefined

bash

undefined

Simple post

简单发布

xurl post "Hello world!"

Post with media (upload first, then attach)

带媒体的发布（先上传，再附加）

xurl media upload photo.jpg # → note the media_id from response xurl post "Check this out" --media-id MEDIA_ID

xurl media upload photo.jpg # → 记录响应中的media_id xurl post "Check this out" --media-id MEDIA_ID

Multiple media

多媒体发布

xurl post "Thread pics" --media-id 111 --media-id 222

Reply to a post (by ID or URL)

回复帖子（通过ID或URL）

xurl reply 1234567890 "Great point!" xurl reply https://x.com/user/status/1234567890 "Agreed!"

Reply with media

带媒体的回复

xurl reply 1234567890 "Look at this" --media-id MEDIA_ID

Quote a post

引用帖子

xurl quote 1234567890 "Adding my thoughts"

Delete your own post

删除自己的帖子

xurl delete 1234567890

undefined

xurl delete 1234567890

undefined

Reading

查看内容

bash

undefined

bash

undefined

Read a single post (returns author, text, metrics, entities)

查看单个帖子（返回作者、文本、数据指标、实体信息）

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

Search recent posts (default 10 results)

搜索近期帖子（默认返回10条结果）

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

undefined

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

undefined

User Info

用户信息

bash

undefined

bash

undefined

Your own profile

查看自己的资料

xurl whoami

Look up any user

查询任意用户信息

xurl user elonmusk xurl user @XDevelopers

undefined

xurl user elonmusk xurl user @XDevelopers

undefined

Timelines & Mentions

时间线与提及内容

bash

undefined

bash

undefined

Home timeline (reverse chronological)

首页时间线（按时间倒序）

xurl timeline xurl timeline -n 25

Your mentions

查看提及我的内容

xurl mentions xurl mentions -n 20

undefined

xurl mentions xurl mentions -n 20

undefined

Engagement

互动操作

bash

undefined

bash

undefined

Like / unlike

点赞/取消点赞

xurl like 1234567890 xurl unlike 1234567890

Repost / undo

转发/取消转发

xurl repost 1234567890 xurl unrepost 1234567890

Bookmark / remove

收藏/取消收藏

xurl bookmark 1234567890 xurl unbookmark 1234567890

List your bookmarks / likes

查看我的收藏/点赞列表

xurl bookmarks -n 20 xurl likes -n 20

undefined

xurl bookmarks -n 20 xurl likes -n 20

undefined

Social Graph

社交关系

bash

undefined

bash

undefined

Follow / unfollow

关注/取消关注

xurl follow @XDevelopers xurl unfollow @XDevelopers

List who you follow / your followers

查看我关注的用户/我的粉丝

xurl following -n 50 xurl followers -n 50

List another user's following/followers

查看其他用户的关注/粉丝列表

xurl following --of elonmusk -n 20 xurl followers --of elonmusk -n 20

Block / unblock

屏蔽/取消屏蔽

xurl block @spammer xurl unblock @spammer

Mute / unmute

静音/取消静音

xurl mute @annoying xurl unmute @annoying

undefined

xurl mute @annoying xurl unmute @annoying

undefined

Direct Messages

私信

bash

undefined

bash

undefined

Send a DM

发送私信

xurl dm @someuser "Hey, saw your post!"

List recent DM events

查看近期私信事件

xurl dms xurl dms -n 25

undefined

xurl dms xurl dms -n 25

undefined

Media Upload

媒体上传

bash

undefined

bash

undefined

Upload a file (auto‑detects type for images/videos)

上传文件（自动检测图片/视频类型）

xurl media upload photo.jpg xurl media upload video.mp4

Specify type and category explicitly

明确指定类型和分类

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

Check processing status (videos need server‑side processing)

检查处理状态（视频需要服务器端处理）

xurl media status MEDIA_ID xurl media status --wait MEDIA_ID # poll until done

xurl media status MEDIA_ID xurl media status --wait MEDIA_ID # 轮询直到处理完成

Full workflow: upload then post

完整流程：上传后发布

xurl media upload meme.png # response includes media id xurl post "lol" --media-id MEDIA_ID

---

xurl media upload meme.png # 响应包含媒体ID xurl post "lol" --media-id MEDIA_ID

---

Global Flags

全局标志

These flags work on every command:

Flag	Short	Description
`--app`		Use a specific registered app for this request (overrides default)
`--auth`		Force auth type: `oauth1` , `oauth2` , or `app`
`--username`	`-u`	Which OAuth2 account to use (if you have multiple)
`--verbose`	`-v`	Forbidden in agent/LLM sessions (can leak auth headers/tokens)
`--trace`	`-t`	Add `X-B3-Flags: 1` trace header

这些标志适用于所有命令：

标志	简写	描述
`--app`		为此请求使用特定的已注册应用（覆盖默认应用）
`--auth`		强制指定认证类型： `oauth1` 、 `oauth2` 或 `app`
`--username`	`-u`	指定使用哪个OAuth2账户（如果有多个账户）
`--verbose`	`-v`	Agent/LLM会话中禁止使用（可能泄露认证头部/令牌）
`--trace`	`-t`	添加 `X-B3-Flags: 1` 追踪头部

Raw API Access

原生API访问

The shortcut commands cover the most common operations. For anything else, use xurl's raw curl‑style mode — it works with any X API v2 endpoint:

bash

undefined

快捷命令覆盖了最常见的操作。对于其他操作，可使用xurl的原生curl风格模式——它适用于任何X API v2端点：

bash

undefined

GET request (default)

GET请求（默认）

xurl /2/users/me

POST with JSON body

带JSON请求体的POST请求

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

PUT, PATCH, DELETE

PUT、PATCH、DELETE请求

xurl -X DELETE /2/tweets/1234567890

Custom headers

自定义头部

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

Force streaming mode

强制流式模式

xurl -s /2/tweets/search/stream

Multipart/form-data file upload

多部分表单数据文件上传

xurl -X POST -F path/to/file.mp4 '/2/media/upload?command=APPEND&media_id=MEDIA_ID&segment_index=0'

Full URLs also work

完整URL同样适用

xurl https://api.x.com/2/users/me

undefined

xurl https://api.x.com/2/users/me

undefined

Raw API Flags

原生API标志

Flag	Short	Description
`-X METHOD`		HTTP method: `GET` , `POST` , `PUT` , `DELETE` , …
`-d BODY`		Request body (JSON string)
`-H HEADER`		Add a header (repeatable)
`-F FILE`		Multipart form-data file (for binary uploads)
`--stream`	`-s`	Force streaming mode for any endpoint

标志	简写	描述
`-X METHOD`		HTTP方法： `GET` 、 `POST` 、 `PUT` 、 `DELETE` 等
`-d BODY`		请求体（JSON字符串）
`-H HEADER`		添加请求头部（可重复使用）
`-F FILE`		多部分表单数据文件（用于二进制上传）
`--stream`	`-s`	为任意端点强制启用流式模式

Direct Media Upload (Advanced)

直接媒体上传（进阶）

For large or non-standard media, you can drive the chunked upload API directly with raw mode:

bash

undefined

对于大型或非标准媒体，你可以通过原生模式直接驱动分块上传API：

bash

undefined

1. Initialize: declare file size, type, and category

1. 初始化：声明文件大小、类型和分类

xurl -X POST '/2/media/upload?command=INIT&total_bytes=FILE_SIZE&media_type=video/mp4&media_category=tweet_video'

2. Append chunks (repeat for each chunk with segment_index=0, 1, 2, …)

2. 追加分块（每个分块重复执行，segment_index依次为0、1、2……）

xurl -X POST -F path/to/file.mp4 '/2/media/upload?command=APPEND&media_id=MEDIA_ID&segment_index=0'

3. Finalize

3. 完成上传

xurl -X POST '/2/media/upload?command=FINALIZE&media_id=MEDIA_ID'

4. Check processing status (videos need server-side processing time)

4. 检查处理状态（视频需要服务器端处理时间）

xurl '/2/media/upload?command=STATUS&media_id=MEDIA_ID'

or use the shortcut:

或使用快捷命令：

xurl media status --wait MEDIA_ID


For most images and short videos, the `xurl media upload` shortcut handles all of this automatically.

---

xurl media status --wait MEDIA_ID


对于大多数图片和短视频，`xurl media upload`快捷命令会自动处理上述所有步骤。

---

Streaming

流式传输

Streaming endpoints are auto‑detected. Known streaming endpoints include:

```
/2/tweets/search/stream
```
```
/2/tweets/sample/stream
```
```
/2/tweets/sample10/stream
```
```
/2/tweets/firehose/stream/lang/en
```
```
/2/tweets/firehose/stream/lang/ja
```
```
/2/tweets/firehose/stream/lang/ko
```
```
/2/tweets/firehose/stream/lang/pt
```

You can force streaming on any endpoint with

-s

bash

xurl -s /2/some/endpoint

流式端点会被自动检测。已知的流式端点包括：

```
/2/tweets/search/stream
```
```
/2/tweets/sample/stream
```
```
/2/tweets/sample10/stream
```
```
/2/tweets/firehose/stream/lang/en
```
```
/2/tweets/firehose/stream/lang/ja
```
```
/2/tweets/firehose/stream/lang/ko
```
```
/2/tweets/firehose/stream/lang/pt
```

你可以使用

-s

标志为任意端点强制启用流式模式：

bash

xurl -s /2/some/endpoint

Webhooks

xurl

can spin up a temporary local webhook server backed by ngrok for development and testing:

bash

undefined

xurl

可以启动一个临时的本地Webhook服务器，借助ngrok实现开发和测试：

bash

undefined

Start local server + ngrok tunnel

启动本地服务器 + ngrok隧道

xurl webhook start

Custom port and log POST bodies to file

自定义端口并将POST请求体记录到文件

xurl webhook start -p 8081 -o webhook_events.log


The command outputs a public ngrok URL (e.g. `https://abc123.ngrok-free.app/webhook`). Use that URL to register a webhook with the X API:

```bash

xurl webhook start -p 8081 -o webhook_events.log


该命令会输出一个公开的ngrok URL（例如`https://abc123.ngrok-free.app/webhook`）。使用此URL向X API注册Webhook：

```bash

Register the webhook (use app authentication)

注册Webhook（使用应用认证）

xurl --auth app /2/webhooks -d '{"url": "https://abc123.ngrok-free.app/webhook"}' -X POST


`xurl webhook start` handles the CRC handshake automatically and logs incoming POST events. Set `NGROK_AUTHTOKEN` in the environment to skip the interactive ngrok authtoken prompt.

---

xurl --auth app /2/webhooks -d '{"url": "https://abc123.ngrok-free.app/webhook"}' -X POST


`xurl webhook start`会自动处理CRC握手并记录传入的POST事件。在环境变量中设置`NGROK_AUTHTOKEN`可跳过交互式ngrok令牌提示。

---

Output Format

输出格式

All commands return JSON to stdout, pretty‑printed with syntax highlighting. The output structure matches the X API v2 response format. A typical response looks like:

json

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

Errors are also returned as JSON:

json

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

所有命令均向标准输出返回JSON格式结果，并带有语法高亮的美化打印。输出结构与X API v2响应格式一致。典型的响应如下：

json

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

错误信息同样以JSON格式返回：

json

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

Common Workflows

常见工作流

Post with an image

发布带图片的帖子

bash

undefined

bash

undefined

1. Upload the image

1. 上传图片

xurl media upload photo.jpg

2. Copy the media_id from the response, then post

2. 复制响应中的media_id，然后发布

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

undefined

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

undefined

Reply to a conversation

回复对话

bash

undefined

bash

undefined

1. Read the post to understand context

1. 查看帖子了解上下文

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

2. Reply

2. 回复

xurl reply 1234567890 "Here are my thoughts..."

undefined

xurl reply 1234567890 "Here are my thoughts..."

undefined

Search and engage

搜索并互动

bash

undefined

bash

undefined

1. Search for relevant posts

1. 搜索相关帖子

xurl search "topic of interest" -n 10

2. Like an interesting one

2. 点赞感兴趣的帖子

xurl like POST_ID_FROM_RESULTS

3. Reply to it

3. 回复该帖子

xurl reply POST_ID_FROM_RESULTS "Great point!"

undefined

xurl reply POST_ID_FROM_RESULTS "Great point!"

undefined

Check your activity

查看你的活动

bash

undefined

bash

undefined

See who you are

查看当前用户信息

xurl whoami

Check your mentions

查看提及我的内容

xurl mentions -n 20

Check your timeline

查看首页时间线

xurl timeline -n 20

undefined

xurl timeline -n 20

undefined

Set up multiple apps

设置多个应用

bash

undefined

bash

undefined

App credentials must already be configured manually outside agent/LLM context.

应用凭据必须已在Agent/LLM上下文外手动配置完成。

Authenticate users on each pre-configured app

在每个预配置的应用上认证用户

xurl auth default prod xurl auth oauth2 # authenticates on prod app

xurl auth default staging xurl auth oauth2 # authenticates on staging app

xurl auth default prod xurl auth oauth2 # 在prod应用上完成认证

xurl auth default staging xurl auth oauth2 # 在staging应用上完成认证

Switch between them

在应用间切换

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

---

xurl auth default prod alice # prod应用，alice用户 xurl --app staging /2/users/me # 单次请求使用staging应用

---

Error Handling

错误处理

Non‑zero exit code on any error.
API errors are printed as JSON to stdout (so you can still parse them).
Auth errors suggest re‑running
```
xurl auth oauth2
```
or checking your tokens.
If a command requires your user ID (like, repost, bookmark, follow, etc.), xurl will automatically fetch it via
```
/2/users/me
```
. If that fails, you'll see an auth error.

任何错误都会返回非零退出码。
API错误会以JSON格式打印到标准输出（因此你仍可解析它们）。
认证错误会建议重新运行
```
xurl auth oauth2
```
或检查令牌。
如果命令需要你的用户ID（如点赞、转发、收藏、关注等），xurl会自动通过
```
/2/users/me
```
获取。如果获取失败，你会看到认证错误。

Notes

注意事项

Rate limits: The X API enforces rate limits per endpoint. If you get a 429 error, wait and retry. Write endpoints (post, reply, like, repost) have stricter limits than read endpoints.
Scopes: OAuth 2.0 tokens are requested with broad scopes. If you get a 403 on a specific action, your token may lack the required scope — re‑run
```
xurl auth oauth2
```
to get a fresh token.
Token refresh: OAuth 2.0 tokens auto‑refresh when expired. No manual intervention needed.
Multiple apps: Each app has its own isolated credentials and tokens. Configure credentials manually outside agent/LLM context, then switch with
```
xurl auth default
```
or
```
--app
```
.
Multiple accounts: You can authenticate multiple OAuth 2.0 accounts per app and switch between them with
```
--username
```
/
```
-u
```
or set a default with
```
xurl auth default APP USER
```
.
Default user: When no
```
-u
```
flag is given, xurl uses the default user for the active app (set via
```
xurl auth default
```
). If no default user is set, it uses the first available token.
Token storage:
```
~/.xurl
```
is YAML. Each app stores its own credentials and tokens. Never read or send this file to LLM context.
client-forbidden
/
client-not-enrolled
errors: If OAuth succeeds but reads (like
```
xurl whoami
```
) fail with these errors, the fix is to move the app to the
```
Pay-per-use
```
package in the
```
Production
```
environment via the X developer console (
```
Apps → Manage apps → Move to package
```
). This is an X platform enrollment issue, not a local xurl issue.
Username not returned by
/2/users/me
: On some X developer accounts,
```
/2/users/me
```
may not reliably return your username after auth. Work around this by authenticating with an explicit handle:
```
xurl auth oauth2 YOUR_USERNAME
```
.

速率限制： X API对每个端点实施速率限制。如果收到429错误，请等待后重试。写入端点（发布、回复、点赞、转发）的限制比读取端点更严格。
权限范围： OAuth 2.0令牌请求使用广泛的权限范围。如果某个特定操作返回403错误，你的令牌可能缺少所需的权限范围——重新运行
```
xurl auth oauth2
```
获取新令牌。
令牌刷新： OAuth 2.0令牌过期时会自动刷新，无需手动干预。
多应用管理： 每个应用都有独立的凭据和令牌存储。请在Agent/LLM上下文外手动配置凭据，然后使用
```
xurl auth default
```
或
```
--app
```
切换应用。
多账户管理： 你可以在每个应用上认证多个OAuth 2.0账户，并使用
```
--username
```
/
```
-u
```
切换，或通过
```
xurl auth default APP USER
```
设置默认账户。
默认用户： 未指定
```
-u
```
标志时，xurl会使用当前活动应用的默认用户（通过
```
xurl auth default
```
设置）。如果未设置默认用户，则使用第一个可用的令牌。
令牌存储：
```
~/.xurl
```
是YAML格式文件。每个应用存储自己的凭据和令牌。切勿读取或发送此文件到LLM上下文。
client-forbidden
/
client-not-enrolled
错误：如果OAuth认证成功，但读取操作（如
```
xurl whoami
```
）返回这些错误，解决方案是通过X开发者控制台（
```
Apps → Manage apps → Move to package
```
）将应用迁移到
```
Production
```
环境下的
```
Pay-per-use
```
套餐。这是X平台的注册问题，而非本地xurl的问题。
/2/users/me
未返回用户名：在某些X开发者账户中，认证后
```
/2/users/me
```
可能无法可靠返回用户名。解决方法是使用明确的用户名进行认证：
```
xurl auth oauth2 YOUR_USERNAME
```
。