gem-hunter
Language: Python
A CLI for Twitter/X — feed, bookmarks, and user timeline in terminal
A terminal-first CLI for Twitter/X: read timelines, bookmarks, and user profiles without API keys.
Read:
for-you and following feedsshow <N> to open tweet #N from the last list output--full-text: disable tweet text truncation in rich table outputAI Agent Tip: Prefer
--yamlfor structured output unless a strict JSON parser is required. Non-TTY stdout defaults to YAML automatically. Use--maxto limit results.
Write:
favorite/unfavorite kept as compatibility aliases)--json / --yaml output nowAuth & Anti-Detection:
curl_cffi with dynamic Chrome version matchingx-client-transaction-id header generationTWITTER_PROXY environment variable# Recommended: uv tool (fast, isolated) uv tool install twitter-cli # Alternative: pipx pipx install twitter-cli
Upgrade to the latest version:
uv tool upgrade twitter-cli
# Or: pipx upgrade twitter-cliTip: Upgrade regularly to avoid unexpected errors from outdated API handling.
Install from source:
git clone git@github.com:jackwener/twitter-cli.git
cd twitter-cli
uv sync# Fetch home timeline (For You) twitter feed # Fetch Following timeline twitter feed -t following # Enable ranking filter explicitly twitter feed --filter
# Feed twitter feed --max 50 twitter feed --cursor "<next-cursor-from-previous-response>" twitter feed --full-text twitter feed --output tweets.json twitter feed --input tweets.json twitter feed --json # Structured stdout for scripts/agents # Bookmarks twitter bookmarks twitter bookmarks --full-text twitter bookmarks --max 30 --yaml # Search twitter search "Claude Code" twitter search "AI agent" -t Latest --max 50 twitter search "AI agent" --full-text twitter search "机器学习" --yaml twitter search "python" --from elonmusk --lang en --since 2026-01-01 twitter search --from bbc --exclude retweets --has links twitter search "topic" -o results.json # Save to file twitter search "trending" --filter # Apply ranking filter # Tweet detail (view tweet + replies) twitter tweet 1234567890 twitter tweet 1234567890 --full-text twitter tweet https://x.com/user/status/1234567890 # Open tweet by index from last list output twitter show 2 # Open tweet #2 from last feed/search twitter show 2 --full-text # Full text in reply table twitter show 2 --json # Structured output # Twitter Article twitter article 1234567890 twitter article https://x.com/user/article/1234567890 --json twitter article 1234567890 --markdown twitter article 1234567890 --output article.md # List timeline twitter list 1539453138322673664 twitter list 1539453138322673664 --cursor "<next-cursor-from-previous-response>" twitter list 1539453138322673664 --full-text # User twitter user elonmusk twitter user-posts elonmusk --max 20 twitter user-posts elonmusk --full-text twitter user-posts elonmusk -o tweets.json twitter likes elonmusk --max 30 # ⚠️ own likes only (private since Jun 2024) twitter likes elonmusk --full-text twitter likes elonmusk -o likes.json twitter followers elonmusk --max 50 twitter following elonmusk --max 50 # Write operations twitter post "Hello from twitter-cli!" twitter post "Hello!" --image photo.jpg # Post with image twitter post "Gallery" -i a.png -i b.jpg -i c.webp # Up to 4 images twitter post "reply text" --reply-to 1234567890 twitter reply 1234567890 "Nice!" -i screenshot.png # Reply with image twitter quote 1234567890 "Look" -i chart.png # Quote with image twitter post "Hello from twitter-cli!" --json twitter delete 1234567890 twitter like 1234567890 twitter like 1234567890 --yaml twitter unlike 1234567890 twitter retweet 1234567890 twitter unretweet 1234567890 twitter bookmark 1234567890 twitter unbookmark 1234567890 twitter follow elonmusk --json
twitter-cli uses this auth priority:
TWITTER_AUTH_TOKEN + TWITTER_CT0Browser extraction is recommended — it forwards ALL Twitter cookies (not just auth_token + ct0) and aligns request headers with your local runtime, which is closer to normal browser traffic than minimal cookie auth.
Chrome multi-profile: All Chrome profiles are scanned automatically. To specify a profile:
TWITTER_CHROME_PROFILE="Profile 2" twitter feedBrowser priority: If you have multiple browsers, set TWITTER_BROWSER to try a specific browser first:
TWITTER_BROWSER=chrome twitter feed # Supported: arc, chrome, edge, firefox, braveAfter loading cookies, the CLI performs lightweight verification. Commands that require account access fail fast on clear auth errors (401/403).
Set TWITTER_PROXY to route all requests through a proxy:
# HTTP proxy export TWITTER_PROXY=http://127.0.0.1:7890 # SOCKS5 proxy export TWITTER_PROXY=socks5://127.0.0.1:1080
Using a proxy can help reduce IP-based rate limiting risks.
Create config.yaml in your working directory:
fetch: count: 50 filter: mode: "topN" # "topN" | "score" | "all" topN: 20 minScore: 50 lang: [] excludeRetweets: false weights: likes: 1.0 retweets: 3.0 replies: 2.0 bookmarks: 5.0 views_log: 0.5 rateLimit: requestDelay: 2.5 # base delay between requests (randomized ×0.7–1.5) maxRetries: 3 # retry count on rate limit (429) retryBaseDelay: 5.0 # base delay for exponential backoff maxCount: 200 # hard cap on fetched items
Fetch behavior:
fetch.count is the default item count for read commands when --max is omitted--full-text to show full body text in list viewsFilter behavior:
--filter is passed--filter: tweets are scored/sorted using config.filterScoring formula:
score = likes_w * likes
+ retweets_w * retweets
+ replies_w * replies
+ bookmarks_w * bookmarks
+ views_log_w * log10(max(views, 1))
Mode behavior:
mode: "topN" keeps the highest topN tweets by scoremode: "score" keeps tweets where score >= minScoremode: "all" returns all tweets after sorting by scoreTWITTER_PROXY to avoid direct IP exposure--max 20 instead of --max 500--full-text when reading long posts in terminal tables--yaml or --json for scripts and agent pipelines-c / --compact when token efficiency matters more than completenessNo Twitter cookies found
x.com in a supported browser (Arc/Chrome/Edge/Firefox/Brave).TWITTER_AUTH_TOKEN and TWITTER_CT0 manually.-v to see browser extraction diagnostics.Cookie expired or invalid (HTTP 401/403)
x.com and retry.Unable to get key for cookie decryption (macOS Keychain)
security unlock-keychain ~/Library/Keychains/login.keychain-dbTwitter API error 404
Invalid tweet JSON file
twitter feed --json > tweets.json.Windows: no output captured by pipe/subprocess (AI agent integration)
"windowsEnableConpty": false in your terminal settings.UnicodeEncodeError: 'gbk'. Git Bash handles UTF-8 natively.subprocess.run(capture_output=True) and file redirection (> file 2>&1) work correctly regardless of ConPTY.Structured error codes commonly include not_authenticated, not_found, invalid_input, rate_limited, and api_error.
# Install dev dependencies uv sync --extra dev # Lint + tests uv run ruff check . uv run pytest -q
Current CI validates the project on Python 3.8, 3.10, and 3.12.
twitter_cli/
├── __init__.py
├── cli.py
├── client.py
├── graphql.py # GraphQL query IDs, URL building, JS bundle scanning
├── parser.py # Tweet, User, Media parsing logic
├── auth.py
├── config.py
├── constants.py
├── exceptions.py
├── filter.py
├── formatter.py
├── output.py
├── serialization.py
└── models.py
twitter-cli ships with a SKILL.md so AI agents can execute common X/Twitter workflows.
npx skills add jackwener/twitter-cli
| Flag | Description |
|---|---|
-g |
Install globally (user-level, shared across projects) |
-a claude-code |
Target a specific agent |
-y |
Non-interactive mode |
mkdir -p .agents/skills git clone git@github.com:jackwener/twitter-cli.git .agents/skills/twitter-cli
⚠️ ClawHub install method is deprecated and no longer supported. Use Skills CLI or Manual Install above.
读取:
for-you 和 followingshow <N> 可直接打开上次列表里的第 N 条推文--full-text：在 rich table 输出里关闭推文正文截断AI Agent 提示： 需要结构化输出时优先使用
--yaml，除非下游必须是 JSON。stdout 不是 TTY 时默认输出 YAML。用--max控制返回数量。
写入:
favorite/unfavorite 兼容别名）--json / --yaml认证与反风控:
curl_cffi 动态匹配 Chrome 版本x-client-transaction-id 请求头生成TWITTER_PROXY 环境变量# 推荐：uv tool
uv tool install twitter-cli升级到最新版本：
uv tool upgrade twitter-cli
# 或：pipx upgrade twitter-cli提示： 建议定期升级，避免因版本过旧导致的 API 调用异常。
# 时间线 twitter feed twitter feed -t following twitter feed --filter twitter feed --full-text twitter feed --cursor "<上一页返回的 nextCursor>" # 收藏 twitter bookmarks twitter bookmarks --full-text # 搜索 twitter search "Claude Code" twitter search "AI agent" -t Latest --max 50 twitter search "AI agent" --full-text twitter search "topic" -o results.json # 保存到文件 twitter search "trending" --filter # 启用排序筛选 # 推文详情 twitter tweet 1234567890 twitter tweet 1234567890 --full-text # 通过序号打开上次列表里的推文 twitter show 2 # 打开上次 feed/search 的第 2 条 twitter show 2 --full-text # 在回复表格里显示完整正文 twitter show 2 --json # 结构化输出 # Twitter 长文 twitter article 1234567890 twitter article https://x.com/user/article/1234567890 --json twitter article 1234567890 --markdown twitter article 1234567890 --output article.md # 列表时间线 twitter list 1539453138322673664 twitter list 1539453138322673664 --cursor "<上一页返回的 nextCursor>" twitter list 1539453138322673664 --full-text # 用户 twitter user elonmusk twitter user-posts elonmusk --max 20 twitter user-posts elonmusk --full-text twitter user-posts elonmusk -o tweets.json twitter likes elonmusk --max 30 # ⚠️ 仅可查看自己的点赞（2024年6月起平台已私密化） twitter likes elonmusk --full-text twitter likes elonmusk -o likes.json twitter followers elonmusk twitter following elonmusk # 写操作 twitter post "你好，世界！" twitter post "发图" --image photo.jpg # 带图发推 twitter post "多图" -i a.png -i b.jpg -i c.webp # 最多 4 张图片 twitter post "回复内容" --reply-to 1234567890 twitter reply 1234567890 "回复" -i screenshot.png # 带图回复 twitter quote 1234567890 "评论" -i chart.png # 带图引用 twitter post "你好，世界！" --json twitter delete 1234567890 twitter like 1234567890 twitter like 1234567890 --yaml twitter unlike 1234567890 twitter retweet 1234567890 twitter unretweet 1234567890 twitter bookmark 1234567890 twitter unbookmark 1234567890 twitter follow elonmusk --json
认证优先级：
TWITTER_AUTH_TOKEN + TWITTER_CT0推荐使用浏览器提取方式，会转发所有 Twitter Cookie，并按本机运行环境生成语言和平台请求头；它比仅发送 auth_token + ct0 更接近普通浏览器流量，但不等于完整浏览器自动化。
Chrome 多 Profile 支持：会自动遍历所有 Chrome profile。也可以通过环境变量指定：
TWITTER_CHROME_PROFILE="Profile 2" twitter feed浏览器优先级：如果有多个浏览器，可通过 TWITTER_BROWSER 指定优先尝试的浏览器：
TWITTER_BROWSER=chrome twitter feed # 支持: arc, chrome, edge, firefox, brave设置 TWITTER_PROXY 环境变量即可：
export TWITTER_PROXY=http://127.0.0.1:7890 # 或 SOCKS5 export TWITTER_PROXY=socks5://127.0.0.1:1080
使用代理可以降低 IP 维度的风控风险。
未传 --max 时，所有读取命令默认使用 config.yaml 里的 fetch.count。
rich table 输出默认会截断较长正文；如果需要在列表视图中查看完整正文，可加 --full-text。
只有在传入 --filter 时才会启用筛选评分；默认不筛选。
评分公式：
score = likes_w * likes
+ retweets_w * retweets
+ replies_w * replies
+ bookmarks_w * bookmarks
+ views_log_w * log10(max(views, 1))
模式说明：
mode: "topN"：按分数排序后保留前 topN 条mode: "score"：仅保留 score >= minScore 的推文mode: "all"：按分数排序后全部保留报错 No Twitter cookies found：请先登录 x.com，并确认浏览器为 Arc/Chrome/Edge/Firefox/Brave 之一，或手动设置环境变量。
如需查看浏览器提取细节，可加 -v 打开诊断日志。
报错 Cookie expired or invalid：Cookie 过期，重新登录后重试。
报错 Unable to get key for cookie decryption（macOS Keychain 问题）：
security unlock-keychain ~/Library/Keychains/login.keychain-db报错 Twitter API error 404：通常是 queryId 轮换，重试即可。
Windows 下 pipe/subprocess 无法捕获输出（AI agent 集成场景）
"windowsEnableConpty": false。UnicodeEncodeError: 'gbk'。Git Bash 原生支持 UTF-8。subprocess.run(capture_output=True) 和文件重定向 (> file 2>&1) 不受此问题影响。结构化错误码通常会区分 not_authenticated、not_found、invalid_input、rate_limited、api_error。
TWITTER_PROXY，避免裸 IP 直连--max 20 而不是 --max 500--full-text--yaml 或 --json-c / --compacttwitter-cli 提供了 SKILL.md，可让 AI Agent 更稳定地调用本工具。
npx skills add jackwener/twitter-cli
| 参数 | 说明 |
|---|---|
-g |
全局安装（用户级别，跨项目共享） |
-a claude-code |
指定目标 Agent |
-y |
非交互模式 |
mkdir -p .agents/skills git clone git@github.com:jackwener/twitter-cli.git .agents/skills/twitter-cli
⚠️ ClawHub 安装方式已过时，不再支持。请使用上方的 Skills CLI 或手动安装。