跳转至

入门指南

本文档帮助你安装 twitter-cli、配置认证，并运行第一条命令。

目录

安装

从源码编译（当前唯一方式）

cargo install x-api-rs --features cli

注意: 首次编译需要下载依赖并编译 Rust 代码，预计耗时 10-15 分钟，请耐心等待。 后续版本（Phase F）将提供预编译二进制，无需本地编译。

编译完成后验证安装：

twitter-cli --version
# twitter-cli 1.0.0

验证帮助信息

# 查看所有命令
twitter-cli --help

# 查看子命令帮助
twitter-cli dm --help
twitter-cli dm send --help

获取 Cookies

twitter-cli 使用 Twitter 账号的浏览器 cookies 进行认证，无需 API Key。

手动从浏览器导出

  1. 浏览器登录 twitter.com
  2. 打开开发者工具（F12 / Cmd+Option+I）
  3. 切换到 Network 标签页
  4. 刷新页面，点击任意请求（如 home.json）
  5. 在请求头中找到 Cookie 字段
  6. 复制完整的 cookies 字符串（包含 ct0、auth_token、twid 等字段）
  7. 保存到文件：
# 创建 cookies 文件（替换 <YOUR_COOKIES_HERE> 为实际内容）
echo 'ct0=xxx; auth_token=xxx; twid=u%3Dxxx; ...' > ~/.x-api/cookies.txt

# 设置正确的文件权限（必须）
chmod 600 ~/.x-api/cookies.txt

参考: 详细的 cookies 导出教程见 https://x-api-rs.es007.com/cli/getting-started/#cookies

Cookies 文件权限要求

CLI 会检查 cookies 文件的 Unix 权限：

权限 行为
0o600 或更严格 正常运行
0o644（其他用户可读） stderr 输出 WARNING，仍运行
0o660 以上（group/other 可写） 拒绝运行，退出码 3（AUTH_FAILED）

推荐权限设置：

chmod 600 ~/.x-api/cookies.txt

认证方式

CLI 支持 4 种认证方式，按以下优先级选择（从高到低）：

方式 1: --cookies-file（推荐，最高优先级）

twitter-cli --cookies-file /path/to/cookies.txt user get --screen-name twitter

适用场景：有多个账号文件，需要明确指定。

方式 2: stdin pipe / --cookies-stdin

# 从文件 pipe（stdin 非 tty 时自动读取，5s 超时）
cat cookies.txt | twitter-cli user get --screen-name twitter

# 显式声明从 stdin 读
twitter-cli --cookies-stdin user get --screen-name twitter
# （然后粘贴 cookies 字符串，按 Ctrl+D 结束）

适用场景：CI/CD 流水线中通过 secret manager 传入 cookies，避免写磁盘。

方式 3: 环境变量

export X_API_COOKIES_FILE=/path/to/cookies.txt
twitter-cli user get --screen-name twitter

适用场景：容器/serverless 环境中统一注入。

方式 4: 配置文件 profile

创建 ~/.x-api/config.toml：

[profile.default]
cookies_file = "~/.x-api/cookies.txt"
proxy = "http://127.0.0.1:8080"   # 可选

[profile.account2]
cookies_file = "~/.x-api/cookies2.txt"

使用：

# 使用 default profile（如果存在则自动选中）
twitter-cli user get --screen-name twitter

# 指定 profile
twitter-cli --profile account2 user get --screen-name twitter

认证优先级总结

--cookies-file > --cookies-stdin/stdin非tty > X_API_COOKIES_FILE > config.toml profile

第一条命令

配置好认证后，运行以下命令验证一切正常：

twitter-cli --cookies-file cookies.txt user get --screen-name twitter

成功输出（格式化展示，实际为一行 JSONL）：

{
  "success": true,
  "data": {
    "id": "783214",
    "name": "Twitter",
    "screen_name": "twitter",
    "description": "What's happening?!",
    "followers_count": 65000000,
    "following_count": 0,
    "verified": true
  },
  "error": null,
  "meta": {
    "module": "user",
    "action": "get",
    "elapsed_ms": 342,
    "timestamp": "2026-04-17T10:45:00Z",
    "cli_version": "1.0.0",
    "schema_version": "1.0"
  }
}

用 jq 提取特定字段：

twitter-cli --cookies-file cookies.txt user get --screen-name twitter | jq '.data.id'
# "783214"

常见错误及修复

AUTH_FAILED — 认证失败

{
  "success": false,
  "data": null,
  "error": {
    "code": "AUTH_FAILED",
    "message": "Twitter 返回 401，cookies 可能已过期或无效",
    "retryable": false,
    "recovery_actions": [
      "重新从浏览器导出 cookies",
      "确认 cookies 文件包含 ct0 和 auth_token 字段"
    ]
  }
}

修复步骤： 1. 重新从浏览器登录 Twitter 并导出 cookies 2. 确认 cookies 字符串包含 ct0=... 和 auth_token=... 字段 3. 检查文件路径是否正确：cat /your/cookies.txt | head -1

权限警告（stderr）

WARN twitter_cli::auth: cookies file permissions are too permissive: mode=0o644, recommend 0o600

文件对其他用户可读，建议：

chmod 600 /your/cookies.txt

CONFIG_PARSE_ERROR — 配置文件格式错误

{
  "success": false,
  "error": {
    "code": "CONFIG_PARSE_ERROR",
    "message": "无法解析 ~/.x-api/config.toml: missing field `cookies_file` at line 3"
  }
}

修复：检查 TOML 格式，参考上方配置文件示例。

NETWORK — 网络错误

{
  "success": false,
  "error": {
    "code": "NETWORK",
    "message": "连接超时",
    "retryable": true,
    "retry_after_secs": null,
    "recovery_actions": ["检查网络连接", "尝试添加 --proxy 参数"]
  }
}

如果需要通过代理访问：

twitter-cli --cookies-file cookies.txt --proxy http://127.0.0.1:8080 user get --screen-name twitter

RATE_LIMIT — 速率限制

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT",
    "message": "请求过于频繁，Twitter 返回 429",
    "retryable": true,
    "retry_after_secs": 900
  }
}

等待 retry_after_secs 秒后重试，或降低请求频率。

下一步