xurl

xurl

使用 xurl 处理 X API 相关操作。快捷命令直接返回 JSON 格式数据；原生模式（raw mode）则支持调用任意 v2 API 端点。

密钥安全

• 严禁读取、打印、总结、上传或查看 ~/.xurl。
• 切勿要求用户在对话框中粘贴 Token 或密钥。
• 请勿使用内联密钥直接运行认证命令。
• 在 Agent 会话中切勿使用 --verbose 参数，这可能会泄漏认证请求头（auth headers）。
• 可通过 xurl auth status 检查当前认证状态。

常用快捷命令

xurl post "Hello world!"
xurl reply POST_ID "Nice."
xurl quote POST_ID "My take"
xurl delete POST_ID
xurl read POST_ID
xurl search "query" -n 20
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 followers -n 20
xurl following -n 20
xurl follow @handle
xurl unfollow @handle
xurl block @handle
xurl unblock @handle
xurl mute @handle
xurl unmute @handle
xurl dm @handle "message"
xurl dms -n 10

POST_ID 可以直接使用完整的 https://x.com/<user>/status/<id> 链接。

媒体处理

xurl media upload image.jpg
xurl media upload clip.mp4
xurl media status MEDIA_ID
xurl post "caption" --media-id MEDIA_ID

视频上传后可能需要处理时间，可通过轮询 media status 查看处理状态。

认证与应用管理

xurl auth status
xurl auth apps list
xurl auth default
xurl auth default APP_NAME USERNAME
xurl auth apps remove APP_NAME

单次请求配置：

xurl --app APP_NAME /2/users/me
xurl --auth oauth2 /2/users/me

原生 API

xurl /2/users/me
xurl -X POST /2/tweets -d '{"text":"Hello world!"}'
xurl '/2/tweets/search/recent?query=openclaw&max_results=10'

当快捷命令无法覆盖所需端点时，请使用原生模式。如需提交复杂的 JSON 请求体（payload），建议将其保存在临时文件中。

输出与错误处理

• 请求成功时，标准输出（stdout）返回 JSON 数据。
• 发生 API、认证或网络错误时，退出码为非 0。
• 401/403：认证、权限范围（scope）或应用不匹配；请运行 xurl auth status 排查。
• 429：触发速率限制（rate limited）；请执行退避重试。
• 媒体上传失败：请检查文件类型、大小以及媒体处理状态。