twitter-cli

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

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

设置

# Install (requires Python 3.8+)
uv tool install twitter-cli
# Or: pipx install twitter-cli

# Upgrade to latest (recommended to avoid API errors)
uv tool upgrade twitter-cli
# Or: pipx upgrade twitter-cli

身份验证

Agent 必读：执行任何 twitter-cli 命令之前，必须先检查是否存在凭据。如果没有，必须主动引导用户完成身份验证流程。不要假设凭据已配置。

重要：写入操作（发布推文、回复、引用）需要完整的浏览器 Cookie。仅通过环境变量提供 auth_token + ct0 可能导致 226 错误（“looks like automated behavior”）。为获得最佳效果，请使用浏览器 Cookie 提取。

步骤 0：检查是否已完成身份验证

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

如果为 AUTH_OK，请跳转到命令参考。 如果为 AUTH_NEEDED，请继续引导用户：

步骤 1：引导用户完成身份验证

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

确保用户已在以下浏览器之一中登录 x.com：Arc、Chrome、Edge、Firefox、Brave。twitter-cli 会自动提取 Cookie。 系统会自动扫描所有 Chrome 配置文件。指定配置文件：TWITTER_CHROME_PROFILE="Profile 2" twitter feed。 优先使用特定浏览器：TWITTER_BROWSER=chrome twitter feed（支持：arc、chrome、edge、firefox、brave）。

twitter whoami

方法 B：环境变量

export TWITTER_AUTH_TOKEN="<auth_token from browser>"
export TWITTER_CT0="<ct0 from browser>"
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="<user's cookie string>"
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：处理常见身份验证问题

症状	Agent 操作
No Twitter cookies found	引导用户在浏览器中登录 x.com，或设置环境变量
读取正常，写入返回 226	缺少完整 Cookie——请使用浏览器 Cookie 提取，而非环境变量
Cookie expired (401/403)	请用户重新登录 x.com，然后重试
用户更改了密码	所有旧 Cookie 均已失效——请重新提取

输出格式

默认：富表格（便于阅读）

twitter feed                          # Pretty table output

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 标志（为大模型减少令牌）

twitter -c feed --max 10              # Minimal fields, great for LLM context
twitter -c search "AI" --max 20       # ~80% fewer tokens than --json

紧凑格式字段（每条推文）： id、author（@handle）、text（截断为 140 个字符）、likes、rts、time（短格式）

命令参考

读取操作

twitter status                         # Quick auth check
twitter status --yaml                  # Structured auth status
twitter whoami                         # Current authenticated user
twitter whoami --yaml                  # YAML output
twitter whoami --json                  # JSON output
twitter user elonmusk                  # User profile
twitter user elonmusk --json           # JSON output
twitter feed                           # Home timeline (For You)
twitter feed -t following              # Following timeline
twitter feed --max 50                  # Limit count
twitter feed --full-text               # Show full post body in table
twitter feed --filter                  # Enable ranking filter
twitter feed --yaml > tweets.yaml      # Export as YAML
twitter feed --input tweets.json       # Read from local JSON file
twitter bookmarks                      # Bookmarked tweets
twitter bookmarks --full-text          # Full text in bookmarks table
twitter bookmarks --max 30 --yaml
twitter search "keyword"               # Search tweets
twitter search "AI agent" -t Latest --max 50
twitter search "AI agent" --full-text  # Full text in search results
twitter search "topic" -o results.json # Save to file
twitter tweet 1234567890               # Tweet detail + replies
twitter tweet 1234567890 --full-text   # Full text in reply table
twitter tweet https://x.com/user/status/12345  # Accepts URL
twitter show 2                         # Open tweet #2 from last feed/search list
twitter show 2 --full-text             # Full text in reply table
twitter show 2 --json                  # Structured output
twitter list 1539453138322673664       # List timeline
twitter list 1539453138322673664 --cursor "<next-cursor>"
twitter list 1539453138322673664 --full-text
twitter user-posts elonmusk --max 20   # User's tweets
twitter user-posts elonmusk --full-text
twitter likes elonmusk --max 30        # User's likes (own only, see note)
twitter likes elonmusk --full-text
twitter followers elonmusk --max 50    # Followers
twitter following elonmusk --max 50    # Following

写入操作

twitter post "Hello from twitter-cli!"              # Post tweet
twitter post "Hello!" --image photo.jpg              # Post with image
twitter post "Gallery" -i a.png -i b.jpg             # Up to 4 images
twitter reply 1234567890 "Great tweet!"              # Reply (standalone)
twitter reply 1234567890 "Nice!" -i pic.png          # Reply with image
twitter post "reply text" --reply-to 1234567890      # Reply (via post)
twitter quote 1234567890 "Interesting take"          # Quote-tweet
twitter quote 1234567890 "Look" -i chart.png         # Quote with image
twitter delete 1234567890                            # Delete tweet
twitter like 1234567890                              # Like
twitter unlike 1234567890                            # Unlike
twitter retweet 1234567890                           # Retweet
twitter unretweet 1234567890                         # Unretweet
twitter bookmark 1234567890                          # Bookmark
twitter unbookmark 1234567890                        # Unbookmark
twitter follow elonmusk                              # Follow user
twitter unfollow elonmusk                            # Unfollow user

图片上传说明：

• 支持的格式：JPEG、PNG、GIF、WebP
• 单张图片最大文件大小：5 MB
• 每条推文最多 4 张图片
• 使用 --image / -i（可重复使用）

Agent 工作流

发布并验证

twitter post "My tweet text" 2>/dev/null
# Output includes tweet URL: 🔗 https://x.com/i/status/<id>

发布带图片的推文

# Single image
twitter post "Check this out!" --image /path/to/photo.jpg

# Multiple images
twitter post "Photo gallery" -i img1.png -i img2.jpg -i img3.webp

回复某人的最新推文

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

创建串文

# Post first tweet, capture output for tweet ID
twitter post "Thread 1/3: First point"
# Note the tweet ID from output, then:
twitter reply <first_tweet_id> "2/3: Second point"
twitter reply <second_tweet_id> "3/3: Final point"

添加评论并引用推文

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"

每日阅读工作流

# Compact mode for token-efficient LLM context
twitter -c feed -t following --max 30
twitter -c bookmarks --max 20

# Rich table with complete post bodies
twitter feed -t following --max 20 --full-text
twitter search "AI agent" --max 20 --full-text

# Full JSON for analysis
twitter feed -t following --max 30 -o following.json
twitter bookmarks --max 20 -o bookmarks.json

使用 jq 过滤搜索结果

# Tweets with > 100 likes
twitter search "AI safety" --max 20 --json | jq '[.data[] | select(.metrics.likes > 100)]'

# Extract just text and author
twitter search "rust lang" --max 10 --json | jq '.data[] | {author: .author.screenName, text: .text[:100]}'

# Most engaged tweets
twitter search "topic" --max 20 --json | jq '.data | sort_by(.metrics.likes) | reverse | .[:5] | .[].id'

排序筛选

筛选为可选功能。使用 --filter 启用：

twitter feed --filter
twitter bookmarks --filter

错误参考

错误	原因	修复方法
No Twitter cookies found	未通过身份验证	在浏览器中登录 x.com，或设置环境变量
HTTP 226	自动化检测	使用浏览器 Cookie 提取（不要使用环境变量）
HTTP 401/403	Cookie 已过期	重新登录 x.com 并重试
HTTP 404	QueryId 轮换	重试（已内置自动回退）
HTTP 429	触发速率限制	等待 15 分钟以上，然后重试
Error 187	推文重复	修改文本内容
Error 186	推文过长	控制在 280 个字符以内

限制

• 仅支持图片 — 暂不支持视频/GIF 动画上传（图片上传支持 JPEG/PNG/GIF/WebP）
• 不支持私信 — 无法发送私信
• 不支持通知 — 无法读取通知
• 不支持投票 — 无法创建投票
• 单个账号 — 一次只能使用一组凭据
• 点赞是私密的 — 自 2024 年 6 月起，Twitter/X 已将所有点赞设为私密。twitter likes 仅适用于你自己的账号

安全注意事项

• 写入操作内置了随机延迟（1.5–4 秒），以避免触发速率限制。
• TLS 指纹和 User-Agent 会自动匹配所用的 Chrome 版本。
• 不要要求用户在聊天记录中分享原始 Cookie 值。
• 优先使用本地浏览器 Cookie 提取，而不是手动复制/粘贴密钥。
• Agent 应将 Cookie 值视为机密（不要在标准输出中无故回显）。