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

检查认证状态。

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.

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上下文外手动运行相关命令。

令牌会以YAML格式持久化存储到

~/.xurl

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

Authorization

请求头。

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`
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)
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`

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`
应用管理
注册应用	手动操作，在Agent外完成（切勿通过Agent传递密钥）
查看应用列表	`xurl auth apps list`
更新应用凭证	手动操作，在Agent外完成（切勿通过Agent传递密钥）
删除应用	`xurl auth apps remove NAME`
设置默认应用（交互式）	`xurl auth default`
设置默认应用（命令式）	`xurl auth default APP_NAME [USERNAME]`
单次请求指定应用	`xurl --app NAME /2/users/me`
认证状态检查	`xurl auth status`

帖子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

Full URLs also work

完整URL也可使用

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

---

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

---

Streaming

流式处理

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

```
/2/tweets/search/stream
```
```
/2/tweets/sample/stream
```
```
/2/tweets/sample10/stream
```

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
```

你可以使用

-s

标志强制对任意端点启用流式处理：

bash

xurl -s /2/some/endpoint

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.

速率限制： 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上下文。