twitter-cli 文档索引¶
twitter-cli 是 x-api-rs 项目附带的命令行工具，设计目标为 AI agent 自动化优先，同时兼顾开发者调试使用。
设计原则¶
- 严格 JSONL 输出 — stdout 只有机器可读的 JSONL，每行一个 JSON 对象，无人类美化装饰
- stderr 日志分离 — tracing 日志全部输出到 stderr，不污染 stdout 管道
- 结构化错误 — 所有错误都包含
code、message、retryable、recovery_actions字段 - 确定性退出码 — 12 种退出码与错误类型一一对应，便于 shell 脚本判断
- 批量三段式格式 — 批量命令输出 header/item/summary 三段，每段独立可流式处理
可用命令¶
| 模块 | 子命令 | 功能 |
|---|---|---|
dm |
send |
发送单条私信 |
dm |
send-batch |
批量发送私信 |
dm |
inbox |
查询私信收件箱 |
posts |
create |
发布帖子 |
posts |
delete |
删除帖子 |
posts |
like |
点赞帖子 |
posts |
unlike |
取消点赞 |
posts |
retweet |
转发帖子 |
posts |
unretweet |
取消转发 |
user |
get |
通过用户名查询用户 |
user |
get-by-id |
通过 ID 查询用户 |
search |
top |
搜索热门帖子 |
search |
latest |
搜索最新帖子 |
upload |
image |
上传图片 |
settings |
get |
查询账号设置 |
共 15 个 action，覆盖 6 个功能模块。
文档导航¶
快速开始¶
- 入门指南 — 安装、认证、第一条命令、常见错误
输出规范¶
- 输出规范 — Envelope/BatchLine/ErrorCode 完整说明，AI agent 解析建议
模块文档¶
| 文档 | 覆盖命令 |
|---|---|
| dm.md | send, send-batch, inbox |
| posts.md | create, delete, like, unlike, retweet, unretweet |
| user.md | get, get-by-id |
| search.md | top, latest |
| upload.md | image |
| settings.md | get |
AI 参考文件¶
- llms.txt — AI 入口索引（精简版，约 50 行）
- llms-full.txt — AI 全量参考（所有命令签名 + 示例，1500-3000 行）
全局 flags 速查¶
所有子命令共享以下 flags：
| Flag | 说明 | 默认值 |
|---|---|---|
--cookies-file <PATH> |
认证：从文件读取 cookies | — |
--cookies-stdin |
认证：从 stdin 读取（5s 超时） | — |
--profile <NAME> |
认证：使用配置文件 profile | — |
--proxy <URL> |
代理 URL | — |
--request-timeout-secs <N> |
单次请求超时（秒） | 30 |
--log-level <LEVEL> |
stderr 日志级别 | off |
--log-format <FORMAT> |
stderr 日志格式 | json |
--ja3 <BOOL> |
JA3/TLS 指纹模拟 | true |
认证优先级¶
1. --cookies-file <path>
2. --cookies-stdin 或 stdin 非 tty（5s 超时）
3. X_API_COOKIES_FILE 环境变量
4. ~/.x-api/config.toml 的 profile.cookies_file
快速示例¶
# 查询用户
twitter-cli --cookies-file cookies.txt user get --screen-name twitter
# 发送私信
twitter-cli --cookies-file cookies.txt dm send --user-id 783214 --text "Hello"
# 搜索帖子（结果用 jq 处理）
twitter-cli --cookies-file cookies.txt search latest --query "rust lang" | jq '.data.tweets[].text'
# 批量发私信
twitter-cli --cookies-file cookies.txt dm send-batch \
--user-ids 783214,6253282 --text "批量测试"
版本信息¶
- CLI 版本：
1.0.0（随库一起版本化） - Schema 版本：
1.0（输出格式版本，Breaking change 升 Major） - 当前状态：所有 15 个 action 均通过真实 API 测试