xurl - X API 命令行工具：支持快捷命令与原始curl，JSON输出，安全认证指南

xurl by steipete/clawdis

302 周安装量

334,400 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/steipete/clawdis --skill xurl

社交网络命令行工具 API

🇨🇳中文介绍

xurl — 代理技能参考

xurl 是一个用于 X API 的命令行工具。它同时支持快捷命令（对人类/代理友好的单行命令）和原始 curl 风格访问任何 v2 端点。所有命令都向标准输出返回 JSON。

安装

Homebrew (macOS)

brew install --cask xdevplatform/tap/xurl

npm

npm install -g @xdevplatform/xurl

Shell 脚本

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

安装到 ~/.local/bin。如果它不在你的 PATH 中，脚本会告诉你需要添加什么。

Go

go install github.com/xdevplatform/xurl@latest

先决条件

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

密钥安全（强制要求）

切勿读取、打印、解析、总结、上传或将 ~/.xurl（或其副本）发送到 LLM 上下文。
切勿要求用户将凭据/令牌粘贴到聊天中。
用户必须在其自己的机器上手动填写 ~/.xurl 所需的密钥。
不要在代理/LLM 会话中推荐或执行带有内联密钥的身份验证命令。
警告：在代理会话中使用 CLI 密钥选项可能会泄露凭据（提示/上下文、日志、shell 历史记录）。
切勿在代理/LLM 会话中使用 --verbose / -v；它可能会在输出中暴露敏感的请求头/令牌。
在代理命令中绝对不能使用的敏感标志：--bearer-token、--consumer-key、--consumer-secret、--access-token、--token-secret、--client-id、--client-secret。
要验证是否至少注册了一个带有凭据的应用，请运行：xurl auth status。

注册应用（推荐）

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

对于多个预先配置的应用，可以在它们之间切换：

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

其他身份验证方法

故意省略了带有内联密钥标志的示例。如果需要 OAuth1 或仅应用身份验证，用户必须在代理/LLM 上下文之外手动运行这些命令。

令牌以 YAML 格式持久化到 ~/.xurl。每个应用都有其独立的令牌。不要通过代理/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`
发送私信	`xurl dm @handle "message"`
列出私信	`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 与 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

# 发送私信
xurl dm @someuser "Hey, saw your post!"

# 列出最近的私信事件
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` 跟踪请求头

快捷命令涵盖了最常见的操作。对于其他任何操作，请使用 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

所有命令都向标准输出返回 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 的一次性请求

任何错误都会返回非零退出码。
API 错误以 JSON 格式打印到标准输出（因此你仍然可以解析它们）。
身份验证错误建议重新运行 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 上下文。

🇺🇸English

xurl — Agent Skill Reference

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.

Installation

Homebrew (macOS)

brew install --cask xdevplatform/tap/xurl

npm

npm install -g @xdevplatform/xurl

Shell script

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.

Go

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.

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, , .

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:

xurl auth oauth2

For multiple pre-configured apps, switch between them:

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

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.

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`

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.

Command Details

Posting

# 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

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

# Reply to a post (by ID or 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

Reading

# 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)
xurl search "golang"
xurl search "from:elonmusk" -n 20
xurl search "#buildinpublic lang:en" -n 15

User Info

# Your own profile
xurl whoami

# Look up any user
xurl user elonmusk
xurl user @XDevelopers

Timelines & Mentions

# Home timeline (reverse chronological)
xurl timeline
xurl timeline -n 25

# Your mentions
xurl mentions
xurl mentions -n 20

Engagement

# 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

Social Graph

# 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

Direct Messages

# Send a DM
xurl dm @someuser "Hey, saw your post!"

# List recent DM events
xurl dms
xurl dms -n 25

Media Upload

# 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

# Full workflow: upload then post
xurl media upload meme.png           # response includes media 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)

Raw API Access

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:

# GET request (default)
xurl /2/users/me

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

# 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
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:

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:

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

Errors are also returned as JSON:

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

Common Workflows

Post with an image

# 1. Upload the image
xurl media upload photo.jpg
# 2. Copy the media_id from the response, then post
xurl post "Check out this photo!" --media-id MEDIA_ID

Reply to a conversation

# 1. Read the post to understand context
xurl read https://x.com/user/status/1234567890
# 2. Reply
xurl reply 1234567890 "Here are my thoughts..."

Search and engage

# 1. Search for relevant posts
xurl search "topic of interest" -n 10
# 2. Like an interesting one
xurl like POST_ID_FROM_RESULTS
# 3. Reply to it
xurl reply POST_ID_FROM_RESULTS "Great point!"

Check your activity

# See who you are
xurl whoami
# Check your mentions
xurl mentions -n 20
# Check your timeline
xurl timeline -n 20

Set up multiple apps

# App credentials must already be configured manually outside agent/LLM context.
# 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

# Switch between them
xurl auth default prod alice           # prod app, alice user
xurl --app staging /2/users/me         # one-off request against 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.

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 ). If no default user is set, it uses the first available token.

Weekly Installs

302

Repository

steipete/clawdis

GitHub Stars

334.4K

First Seen

Feb 22, 2026

Security Audits

Gen Agent Trust HubFail SocketPass SnykFail

Installed on

codex291

opencode288

gemini-cli287

kimi-cli287

cursor287

amp287

Lark CLI IM 即时消息管理工具：机器人/用户身份操作聊天、消息、文件下载

15,600 周安装

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

Token storage: ~/.xurl is YAML. Each app stores its own credentials and tokens. Never read or send this file to LLM context.

xurl - X API 命令行工具：支持快捷命令与原始curl，JSON输出，安全认证指南

🇨🇳中文介绍

xurl — 代理技能参考

安装

Homebrew (macOS)

npm

Shell 脚本

Go

先决条件

相关 Skills

密钥安全（强制要求）

注册应用（推荐）

其他身份验证方法

快速参考

命令详情

发帖

阅读

用户信息

时间线与提及

互动

社交图谱

私信

媒体上传

全局标志

原始 API 访问

流式传输

输出格式

常见工作流

带图片发帖

回复对话

搜索与互动

检查你的活动

设置多个应用

错误处理

注意事项

🇺🇸English

xurl — Agent Skill Reference

Installation

Homebrew (macOS)

npm

Shell script

Go

Prerequisites

Secret Safety (Mandatory)

Register an app (recommended)

Other auth methods

Quick Reference

Command Details

Posting

Reading

User Info

Timelines & Mentions

Engagement

Social Graph

Direct Messages

Media Upload

Global Flags

Raw API Access

Streaming

Output Format

Common Workflows

Post with an image

Reply to a conversation

Search and engage

Check your activity

Set up multiple apps

Error Handling

Notes

最新 Skills