twitter-cli — Twitter/X 命令行工具

二进制文件： twitter 认证凭证： 浏览器 Cookie（自动提取）或环境变量

安装配置

# 安装（需 Python 3.8+）
uv tool install twitter-cli
# 或：pipx install twitter-cli

# 升级至最新版（推荐，避免 API 错误）
uv tool upgrade twitter-cli
# 或：pipx upgrade twitter-cli

认证机制

对 Agent 的重要提示：在执行任何 twitter-cli 命令前，你必须首先检查认证凭证是否存在。若不存在，则必须主动引导用户完成认证流程。请勿假设凭证已配置。

关键说明：写操作（发布推文、回复、引用推文）必须依赖完整浏览器 Cookie。仅通过环境变量提供 auth_token 和 ct0 可能导致 226 错误（“疑似自动化行为”）。为获得最佳效果，请使用浏览器 Cookie 提取方式。

步骤 0：检查是否已认证

twitter status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"

若输出 AUTH_OK，可跳至「命令参考」章节； 若输出 AUTH_NEEDED，请继续引导用户完成以下步骤：

步骤 1：引导用户完成认证

方法 A：浏览器 Cookie 提取（推荐）

请确保用户已在 Arc、Chrome、Edge、Firefox 或 Brave 中登录 x.com。twitter-cli 支持自动提取 Cookie。 所有 Chrome 用户配置文件将被自动扫描。如需指定特定配置文件，请设置：TWITTER_CHROME_PROFILE="Profile 2" twitter feed。

twitter whoami

方法 B：环境变量方式

export TWITTER_AUTH_TOKEN="<从浏览器获取的 auth_token>"
export TWITTER_CT0="<从浏览器获取的 ct0>"
twitter whoami

方法 C：完整 Cookie 字符串（适用于云环境/远程 Agent）

请告知用户：

我需要你的 Twitter 登录凭证。请按以下步骤获取：

1. 使用 Chrome/Edge/Firefox 打开 https://x.com（确保已登录）
2. 按 F12 打开开发者工具 → 切换到 Network 标签页
3. 刷新当前页面，点击任意一条 x.com 请求
4. 在 Request Headers 区域中找到 Cookie: 行，右键 → 复制其值
5. 将完整的 Cookie 字符串发送给我

⚠️ Cookie 包含登录敏感信息，请勿分享给他人。

随后提取并设置环境变量：

FULL_COOKIE="<用户的 Cookie 字符串>"
export TWITTER_AUTH_TOKEN=$(echo "$FULL_COOKIE" | grep -oE 'auth_token=[a-f0-9]+' | cut -d= -f2)
export TWITTER_CT0=$(echo "$FULL_COOKIE" | grep -oE 'ct0=[a-f0-9]+' | cut -d= -f2)
twitter whoami

步骤 2：处理常见认证问题

输出格式

默认格式：富文本表格（面向人类阅读）

twitter feed                          # 美观的表格输出

YAML / JSON：结构化输出

当标准输出非 TTY（例如管道或重定向）时，默认自动使用 YAML 格式。可通过 OUTPUT=yaml|json|rich|auto 显式覆盖。

twitter feed --yaml
twitter feed --json | jq '.[0].text'

所有机器可读输出均遵循 SCHEMA.md 中定义的数据信封结构。 推文与用户数据现统一置于 .data 字段下。

完整正文：--full-text 参数（仅限富文本表格）

当用户希望在终端表格中查看完整推文内容时，请使用 --full-text。该参数影响如下富文本列表视图：feed、bookmarks、search、user-posts、likes、list，以及 tweet 命令中的回复表格。 它不会影响 --json、--yaml 或 -c（紧凑模式）输出。

twitter feed --full-text
twitter search "AI agent" --full-text
twitter user-posts elonmusk --max 20 --full-text
twitter tweet 1234567890 --full-text

紧凑模式：-c 参数（最小化 token 数量，适用于 LLM 上下文）

twitter -c feed --max 10              # 最小字段集，非常适合 LLM 上下文
twitter -c search "AI" --max 20       # token 数量比 --json 减少约 80%

紧凑模式每条推文包含字段：id、author（@handle）、text（截断至 140 字符）、likes、rts、time（简短格式）

命令参考

读操作

twitter status                         # 快速认证检查
twitter status --yaml                  # 结构化认证状态
twitter whoami                         # 当前已认证用户
twitter whoami --yaml                  # YAML 输出
twitter whoami --json                  # JSON 输出
twitter user elonmusk                  # 用户资料页
twitter user elonmusk --json           # JSON 输出
twitter feed                           # 主页时间线（For You）
twitter feed -t following              # 关注时间线
twitter feed --max 50                  # 限制结果数量
twitter feed --full-text               # 在表格中显示完整正文
twitter feed --filter                  # 启用排序过滤器
twitter feed --yaml > tweets.yaml      # 导出为 YAML 文件
twitter feed --input tweets.json       # 从本地 JSON 文件读取
twitter bookmarks                      # 已收藏推文
twitter bookmarks --full-text          # 在收藏表格中显示完整正文
twitter bookmarks --max 30 --yaml
twitter search "keyword"               # 搜索推文
twitter search "AI agent" -t Latest --max 50
twitter search "AI agent" --full-text  # 在搜索结果中显示完整正文
twitter search "topic" -o results.json # 保存至文件
twitter tweet 1234567890               # 推文详情 + 回复
twitter tweet 1234567890 --full-text   # 在回复表格中显示完整正文
twitter tweet https://x.com/user/status/12345  # 支持 URL 输入
twitter list 1539453138322673664       # 列表时间线
twitter list 1539453138322673664 --full-text
twitter user-posts elonmusk --max 20   # 用户发布的推文
twitter user-posts elonmusk --full-text
twitter likes elonmusk --max 30        # 用户点赞的推文（仅限自身账号，详见备注）
twitter likes elonmusk --full-text
twitter followers elonmusk --max 50    # 粉丝列表
twitter following elonmusk --max 50    # 关注列表

写操作

twitter post "Hello from twitter-cli!"              # 发布推文
twitter reply 1234567890 "Great tweet!"              # 单独回复（reply）
twitter post "reply text" --reply-to 1234567890      # 通过 post 命令发起回复
twitter quote 1234567890 "Interesting take"          # 引用推文（quote-tweet）
twitter delete 1234567890                            # 删除推文
twitter like 1234567890                              # 点赞
twitter unlike 1234567890                            # 取消点赞
twitter retweet 1234567890                           # 转推
twitter unretweet 1234567890                         # 取消转推
twitter bookmark 1234567890                          # 收藏
twitter unbookmark 1234567890                        # 取消收藏
twitter follow elonmusk                              # 关注用户
twitter unfollow elonmusk                            # 取关用户

Agent 工作流示例

发布并验证

twitter post "My tweet text" 2>/dev/null
# 输出中包含推文链接：🔗 https://x.com/i/status/

回复某人最新推文

TWEET_ID=$(twitter user-posts targetuser --max 1 --json | jq -r '.data[0].id')
twitter reply "$TWEET_ID" "Nice post!"

创建多推文线程（thread）

# 发布首条推文，并捕获输出以获取 ID
twitter post "Thread 1/3: First point"
# 从输出中记录推文 ID，然后：
twitter reply  "2/3: Second point"
twitter reply  "3/3: Final point"

带评论的引用推文（Quote-tweet）

TWEET_ID=$(twitter search "interesting topic" --max 1 --json | jq -r '.data[0].id')
twitter quote "$TWEET_ID" "This is a great insight!"

批量点赞搜索结果

twitter search "interesting topic" --max 5 --json | jq -r '.data[].id' | while read id; do
  twitter like "$id"
done

获取用户信息后关注

twitter user targethandle --json | jq '.data | {username, followers, bio}'
twitter follow targethandle

查找某用户最热门的推文

twitter user-posts elonmusk --max 20 --json | jq '.data | sort_by(.metrics.likes) | reverse | .[:3] | .[] | {id, text: .text[:80], likes: .metrics.likes}'

检查关注关系

MY_NAME=$(twitter whoami --json | jq -r '.data.user.username')
twitter followers "$MY_NAME" --max 200 --json | jq -r '.data[].username' | grep -q "targetuser" && echo "Yes" || echo "No"

日常阅读工作流

# 紧凑模式：适用于 token 效率优先的 LLM 上下文
twitter -c feed -t following --max 30
twitter -c bookmarks --max 20

# 富文本表格：展示完整正文
twitter feed -t following --max 20 --full-text
twitter search "AI agent" --max 20 --full-text

# 完整 JSON：用于深度分析
twitter feed -t following --max 30 -o following.json
twitter bookmarks --max 20 -o bookmarks.json

结合 jq 的高级搜索过滤

# 筛选获赞数超过 100 的推文
twitter search "AI safety" --max 20 --json | jq '[.data[] | select(.metrics.likes > 100)]'

# 仅提取作者与正文（前 100 字符）
twitter search "rust lang" --max 10 --json | jq '.data[] | {author: .author.screenName, text: .text[:100]}'

# 获取互动最高的 5 条推文 ID
twitter search "topic" --max 20 --json | jq '.data | sort_by(.metrics.likes) | reverse | .[:5] | .[].id'

排序过滤器（Ranking Filter）

过滤功能为可选启用项，通过 --filter 开启：

twitter feed --filter
twitter bookmarks --filter

错误参考

限制说明

• 纯文本支持 — 不支持媒体/图片上传
• 无私信功能 — 不支持 Direct Message（DM）
• 无通知读取 — 无法读取通知中心内容
• 无投票功能 — 不支持创建投票（polls）
• 单账户限制 — 同一时间仅支持一套认证凭证
• 点赞隐私化 — 自 2024 年 6 月起，Twitter/X 已将所有点赞设为私密。twitter likes 仅对当前登录账号有效

安全注意事项

• 写操作内置随机延迟（1.5–4 秒），以规避频率限制。
• TLS 指纹与 User-Agent 将自动匹配所用 Chrome 版本。
• 切勿要求用户在聊天日志中直接发送原始 Cookie 值。
• 优先采用本地浏览器 Cookie 提取，避免手动复制粘贴敏感凭据。
• Agent 应将 Cookie 值视为机密信息（避免不必要的 stdout 输出）。