jackwener/twitter-cli

# twitter-cli [](https://github.com/jackwener/twitter-cli/actions/workflows/ci.yml) [](https://pypi.org/project/twitter-cli/) [](https://pypi.org/project/twitter-cli/) 一款终端优先的 Twitter/X CLI：无需 API keys 即可读取时间线、书签和用户资料。 ## 更多工具 - [xhs-cli](https://github.com/jackwener/xhs-cli) — 小红书 CLI，用于笔记和账号工作流 - [bilibili-cli](https://github.com/jackwener/bilibili-cli) — Bilibili CLI，用于视频、用户、搜索和动态 [English](#english) | [中文](#中文) ## 英语 ### 功能特性 **读取:** - 时间线：获取 `for-you` 和 `following` 信息流 - 书签：列出你账号中保存的推文 - 搜索：通过关键词查找推文，支持 Top/Latest/Photos/Videos 标签页 - 推文详情：查看推文及其回复 - 列表时间线：获取 Twitter List 中的推文 - 用户查询：获取用户资料、推文、点赞、粉丝和关注 - JSON 输出：导出任意数据用于脚本处理 - 可选评分过滤器：按互动权重对推文进行排名 **写入:** - 发推：创建新推文和回复 - 删除：删除你自己的推文 - 点赞 / 取消点赞：管理推文点赞 - 转推 / 取消转推：管理转推 - 收藏：添加/移除书签 **认证与反检测:** - Cookie 认证：使用浏览器 cookies 或环境变量 - 完整 Cookie 转发：提取所有浏览器 cookies 以实现真实的浏览器指纹 - TLS 指纹模拟：`curl_cffi` 配合动态 Chrome 版本匹配 - `x-client-transaction-id` 请求头生成 - 请求时序抖动以避免模式检测 - 写入操作延迟（1.5–4秒随机）以缓解速率限制 - 通过 `TWITTER_PROXY` 环境变量支持代理 ### 安装 ``` # 推荐：uv tool（快速、隔离） uv tool install twitter-cli # 替代方案：pipx pipx install twitter-cli ``` 从源码安装： ``` git clone git@github.com:jackwener/twitter-cli.git cd twitter-cli uv sync ``` ### 快速开始 ``` # 获取主页时间线 twitter feed # 获取 Following 时间线 twitter feed -t following # 显式启用 ranking filter twitter feed --filter ``` ### 使用方法 ``` # Feed twitter feed --max 50 twitter feed --json > tweets.json twitter feed --input tweets.json # Bookmarks twitter favorites twitter favorites --max 30 --json # 搜索 twitter search "Claude Code" twitter search "AI agent" -t Latest --max 50 twitter search "机器学习" --json twitter search "topic" -o results.json # Save to file twitter search "trending" --filter # Apply ranking filter # Tweet 详情（查看 tweet + 回复） twitter tweet 1234567890 twitter tweet https://x.com/user/status/1234567890 # List 时间线 twitter list 1539453138322673664 # User twitter user elonmusk twitter user-posts elonmusk --max 20 twitter user-posts elonmusk -o tweets.json twitter likes elonmusk --max 30 twitter likes elonmusk -o likes.json twitter followers elonmusk --max 50 twitter following elonmusk --max 50 # 写操作 twitter post "Hello from twitter-cli!" twitter post "reply text" --reply-to 1234567890 twitter delete 1234567890 twitter like 1234567890 twitter unlike 1234567890 twitter retweet 1234567890 twitter unretweet 1234567890 twitter favorite 1234567890 twitter unfavorite 1234567890 ``` ### 认证 twitter-cli 使用以下认证优先级： 1. **环境变量**：`TWITTER_AUTH_TOKEN` + `TWITTER_CT0` 2. **浏览器 cookies**（推荐）：从 Chrome/Edge/Firefox/Brave 自动提取 推荐使用浏览器提取方式 —— 它会转发所有 Twitter cookies（不仅仅是 `auth_token` + `ct0`），使请求与真实浏览器流量无法区分。 加载 cookies 后，CLI 会执行轻量级验证。需要账号访问的命令在遇到明确的认证错误（`401/403`）时会快速失败。 ### 代理支持 设置 `TWITTER_PROXY` 以通过代理路由所有请求： ``` # HTTP proxy export TWITTER_PROXY=http://127.0.0.1:7890 # SOCKS5 proxy export TWITTER_PROXY=socks5://127.0.0.1:1080 ``` 使用代理有助于降低基于 IP 的速率限制风险。 ### 配置 在你的工作目录中创建 `config.yaml`： ``` 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 ``` 过滤行为： - 默认行为：除非传入 `--filter`，否则不进行排名过滤 - 使用 `--filter`：使用 `config.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"`：按分数排序后返回所有推文 ### 最佳实践（避免封号） - **使用代理** — 设置 `TWITTER_PROXY` 以避免直接 IP 暴露 - **保持请求量低** — 使用 `--max 20` 而不是 `--max 500` - **不要过于频繁运行** — 每次启动都会获取 x.com 以初始化反检测请求头 - **使用浏览器 cookie 提取** — 提供完整的 cookie 指纹 - **避免数据中心 IP** — 住宅代理更安全 ### 故障排除 - `No Twitter cookies found` - 确保你已在支持的浏览器中登录 `x.com`。 - 或者手动设置 `TWITTER_AUTH_TOKEN` 和 `TWITTER_CT0`。 - `Cookie expired or invalid (HTTP 401/403)` - 重新登录 `x.com` 并重试。 - `Twitter API error 404` - 当上游 GraphQL 查询 ID 轮换时可能会发生这种情况。 - 重试命令；客户端会尝试实时的 queryId 回退。 - `Invalid tweet JSON file` - 使用 `twitter feed --json > tweets.json` 重新生成输入。 ### 开发 ``` # 安装 dev dependencies uv sync --extra dev # Lint + 测试 uv run ruff check . uv run pytest -q ``` ### 项目结构 ``` twitter_cli/ ├── __init__.py ├── cli.py ├── client.py ├── auth.py ├── config.py ├── constants.py ├── filter.py ├── formatter.py ├── serialization.py └── models.py ``` ### 作为 AI Agent Skill 使用 twitter-cli 附带 [`SKILL.md`](./SKILL.md)，以便 AI agents 可以执行常见的 X/Twitter 工作流。 #### Claude Code / Antigravity ``` # Clone 到你的项目 skills 目录中 mkdir -p .agents/skills git clone git@github.com:jackwener/twitter-cli.git .agents/skills/twitter-cli # 或仅复制 SKILL.md curl -o .agents/skills/twitter-cli/SKILL.md \ https://raw.githubusercontent.com/jackwener/twitter-cli/main/SKILL.md ``` #### OpenClaw / ClawHub 从 ClawHub 安装： ``` clawhub install twitter-cli ``` 安装后，OpenClaw 可以直接调用 `twitter-cli` 命令。 ## 中文 ### 功能概览 **读取:** - 时间线读取：支持 `for-you` 和 `following` - 收藏读取：查看账号书签推文 - 搜索：按关键词搜索推文，支持 Top/Latest/Photos/Videos - 推文详情：查看推文及其回复 - 列表时间线：获取 Twitter List 的推文 - 用户查询：查看用户资料、推文、点赞、粉丝和关注 - JSON 输出：便于脚本处理 **写入:** - 发推：发布新推文和回复 - 删除：删除自己的推文 - 点赞 / 取消点赞 - 转推 / 取消转推 - 收藏 / 取消收藏：favorite/unfavorite **认证与反风控:** - Cookie 认证：支持环境变量和浏览器自动提取 - 完整 Cookie 转发：提取浏览器中所有 Twitter Cookie - TLS 指纹伪装：`curl_cffi` 动态匹配 Chrome 版本 - `x-client-transaction-id` 请求头生成 - 请求时序随机化（jitter） - 写操作随机延迟（1.5–4 秒），降低频率风控 - 代理支持：`TWITTER_PROXY` 环境变量 ### 安装 ``` # 推荐：uv tool uv tool install twitter-cli ``` ### 使用指南 ``` # 时间线 twitter feed twitter feed -t following twitter feed --filter # 收藏 twitter favorites # 搜索 twitter search "Claude Code" twitter search "AI agent" -t Latest --max 50 twitter search "topic" -o results.json # 保存到文件 twitter search "trending" --filter # 启用排序筛选 # 推文详情 twitter tweet 1234567890 # 列表时间线 twitter list 1539453138322673664 # 用户 twitter user elonmusk twitter user-posts elonmusk --max 20 twitter user-posts elonmusk -o tweets.json twitter likes elonmusk --max 30 twitter likes elonmusk -o likes.json twitter followers elonmusk twitter following elonmusk # 写操作 twitter post "你好，世界！" twitter post "回复内容" --reply-to 1234567890 twitter delete 1234567890 twitter like 1234567890 twitter unlike 1234567890 twitter retweet 1234567890 twitter unretweet 1234567890 twitter favorite 1234567890 twitter unfavorite 1234567890 ``` ### 认证说明 认证优先级： 1. **环境变量**：`TWITTER_AUTH_TOKEN` + `TWITTER_CT0` 2. **浏览器提取**（推荐）：Chrome/Edge/Firefox/Brave 全量 Cookie 提取 推荐使用浏览器提取方式，会转发所有 Twitter Cookie，让请求和真实浏览器完全一致。 ### 代理支持 设置 `TWITTER_PROXY` 环境变量即可： ``` export TWITTER_PROXY=http://127.0.0.1:7890 # 或 SOCKS5 export TWITTER_PROXY=socks5://127.0.0.1:1080 ``` 使用代理可以降低 IP 维度的风控风险。 ### 筛选算法 只有在传入 `--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` 或手动设置环境变量。 - 报错 `Cookie expired or invalid`：Cookie 过期，重新登录后重试。 - 报错 `Twitter API error 404`：通常是 queryId 轮换，重试即可。 ### 使用建议（防封号） - **使用代理** — 设置 `TWITTER_PROXY`，避免裸 IP 直连 - **控制请求量** — 用 `--max 20` 而不是 `--max 500` - **避免频繁启动** — 每次启动都会访问 x.com 初始化反检测请求头 - **使用浏览器 Cookie 提取** — 提供完整 Cookie 指纹 - **避免数据中心 IP** — 住宅代理更安全 - Cookie 仅在本地使用，不会被本工具上传 ### 作为 AI Agent Skill 使用 twitter-cli 提供了 [`SKILL.md`](./SKILL.md)，可让 AI Agent 更稳定地调用本工具。 #### Claude Code / Antigravity ``` # 克隆到项目 skills 目录 mkdir -p .agents/skills git clone git@github.com:jackwener/twitter-cli.git .agents/skills/twitter-cli # 或仅下载 SKILL.md curl -o .agents/skills/twitter-cli/SKILL.md \ https://raw.githubusercontent.com/jackwener/twitter-cli/main/SKILL.md ``` #### OpenClaw / ClawHub 通过 ClawHub 安装： ``` clawhub install twitter-cli ```

标签：BeEF, CLI, Cookie, curl_cffi, Feed流, Python, TLS指纹伪造, Twitter, WiFi技术, X, 书签管理, 云资产清单, 反爬虫, 开源, 无后门, 爬虫, 社交媒体, 终端, 绕过检测, 网络安全, 网络调试, 自动化, 逆向工具, 逆向工程, 隐私保护, 非官方API