twitter-cli
Use twitter-cli for ALL Twitter/X operations — reading tweets, posting, replying, quoting, liking, retweeting, following, searching, user lookups. Invoke whenever user requests any Twitter interaction.
- License 许可
- Apache-2.0
- 最近更新
- 2026-10-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- twitter-cli
- tags
- [ "twitter", "x", "social-media", "terminal", "cli" ]
- author
- jackwener
- version
- 0.8.0
- description
- Use twitter-cli for ALL Twitter/X operations — reading tweets, posting, replying, quoting, liking, retweeting, following, searching, user lookups. Invoke whenever user requests any Twitter interaction.
02 资源文件 48
- 参考文档.github/ISSUE_TEMPLATE/bug_report.yml2.0 KB
- 参考文档.github/ISSUE_TEMPLATE/feature_request.yml672 B
- 参考文档.github/workflows/ci.yml693 B
- 参考文档.github/workflows/publish.yml578 B
- 其他.gitignore110 B
- 参考文档AGENTS.md2.2 KB
- 参考文档config.yaml461 B
- 许可证LICENSE10.5 KB
- 其他pyproject.toml1.6 KB
- 参考文档README.md21.3 KB
- 参考文档SCHEMA.md1.1 KB
- 脚本tests/conftest.py1.7 KB
- 参考文档tests/fixtures/followers_page.json1.7 KB
- 参考文档tests/fixtures/home_timeline.json8.8 KB
- 参考文档tests/fixtures/list_timeline.json2.9 KB
- 参考文档tests/fixtures/search_timeline.json4.6 KB
- 参考文档tests/fixtures/tweet_detail.json4.4 KB
- 脚本tests/test_auth.py14.6 KB
- 脚本tests/test_cache.py3.3 KB
- 脚本tests/test_cli.py28.8 KB
- 脚本tests/test_client.py61.7 KB
- 脚本tests/test_config_normalization.py2.0 KB
- 脚本tests/test_config.py1.3 KB
- 脚本tests/test_filter.py2.7 KB
- 脚本tests/test_output.py5.0 KB
- 脚本tests/test_parser_fixtures.py3.8 KB
- 脚本tests/test_search.py4.3 KB
- 脚本tests/test_serialization.py2.9 KB
- 脚本tests/test_smoke.py2.7 KB
- 脚本tests/test_timeutil.py2.3 KB
- 脚本twitter_cli/__init__.py175 B
- 脚本twitter_cli/auth.py24.2 KB
- 脚本twitter_cli/cache.py2.2 KB
- 脚本twitter_cli/cli.py54.6 KB
- 脚本twitter_cli/client.py49.7 KB
- 脚本twitter_cli/commands/__init__.py340 B
- 脚本twitter_cli/config.py4.9 KB
- 脚本twitter_cli/constants.py3.1 KB
- 脚本twitter_cli/exceptions.py2.1 KB
- 脚本twitter_cli/filter.py2.9 KB
- 脚本twitter_cli/formatter.py10.2 KB
- 脚本twitter_cli/graphql.py8.7 KB
- 脚本twitter_cli/models.py1.5 KB
- 脚本twitter_cli/output.py4.6 KB
- 脚本twitter_cli/parser.py21.4 KB
- 脚本twitter_cli/search.py3.9 KB
- 脚本twitter_cli/serialization.py8.4 KB
- 脚本twitter_cli/timeutil.py2.3 KB
03 SKILL.md 正文
twitter-cli — Twitter/X CLI Tool
Binary: twitter
Credentials: browser cookies (auto-extracted) or env vars
Setup
# 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
Authentication
IMPORTANT FOR AGENTS: Before executing ANY twitter-cli command, you MUST first check if credentials exist. If not, you MUST proactively guide the user through the authentication process. Do NOT assume credentials are configured.
CRITICAL: Write operations (posting tweets, replying, quoting) REQUIRE full browser cookies. Only providing auth_token + ct0 via env vars may result in 226 error ("looks like automated behavior"). For best results, use browser cookie extraction.
Step 0: Check if already authenticated
twitter status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED"
If AUTH_OK, skip to Command Reference.
If AUTH_NEEDED, proceed to guide the user:
Step 1: Guide user to authenticate
Method A: Browser cookie extraction (recommended)
Ensure user is logged into x.com in one of: Arc, Chrome, Edge, Firefox, Brave. twitter-cli auto-extracts cookies.
All Chrome profiles are scanned automatically. To specify a profile: TWITTER_CHROME_PROFILE="Profile 2" twitter feed.
To prioritize a specific browser: TWITTER_BROWSER=chrome twitter feed (supported: arc, chrome, edge, firefox, brave).
twitter whoami
Method B: Environment variables
export TWITTER_AUTH_TOKEN="<auth_token from browser>"
export TWITTER_CT0="<ct0 from browser>"
twitter whoami
Method C: Full cookie string (for cloud/remote agents)
Tell the user:
我需要你的 Twitter 登录凭证。请按以下步骤获取:
- 用 Chrome/Edge/Firefox 打开 https://x.com(确保已登录)
- 按
F12打开开发者工具 → Network 标签- 在页面上刷新,点击任意
x.com请求- 找到 Request Headers → Cookie: 这一行,右键 → 复制值
- 把完整 Cookie 字符串发给我
⚠️ Cookie 包含登录信息,请不要分享给其他人。
Then extract and set env vars:
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
Step 2: Handle common auth issues
| Symptom | Agent action |
|---|---|
No Twitter cookies found |
Guide user to login to x.com in browser, or set env vars |
| Read works, write returns 226 | Full cookies missing — use browser cookie extraction instead of env vars |
Cookie expired (401/403) |
Ask user to re-login to x.com and retry |
| User changed password | All old cookies invalidated — re-extract |
Output Format
Default: Rich table (human-readable)
twitter feed # Pretty table output
YAML / JSON: structured output
Non-TTY stdout defaults to YAML automatically. Use OUTPUT=yaml|json|rich|auto to override.
twitter feed --yaml
twitter feed --json | jq '.[0].text'
All machine-readable output uses the envelope documented in SCHEMA.md.
Tweet and user payloads now live under .data.
Full text: --full-text flag (rich tables only)
Use --full-text when the user wants complete post bodies in terminal tables.
It affects rich table list views such as feed, bookmarks, search, user-posts, likes, list, and reply tables in tweet.
It does not change --json, --yaml, or -c compact output.
twitter feed --full-text
twitter search "AI agent" --full-text
twitter user-posts elonmusk --max 20 --full-text
twitter tweet 1234567890 --full-text
Compact: -c flag (minimal tokens for LLM)
twitter -c feed --max 10 # Minimal fields, great for LLM context
twitter -c search "AI" --max 20 # ~80% fewer tokens than --json
Compact fields (per tweet): id, author (@handle), text (truncated 140 chars), likes, rts, time (short format)
Command Reference
Read Operations
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
Write Operations
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
Image upload notes:
- Supported formats: JPEG, PNG, GIF, WebP
- Max file size: 5 MB per image
- Max 4 images per tweet
- Use
--image/-i(repeatable)
Agent Workflows
Post and verify
twitter post "My tweet text" 2>/dev/null
# Output includes tweet URL: 🔗 https://x.com/i/status/<id>
Post with images
# 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
Reply to someone's latest tweet
TWEET_ID=$(twitter user-posts targetuser --max 1 --json | jq -r '.data[0].id')
twitter reply "$TWEET_ID" "Nice post!"
Create a thread
# 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"
Quote-tweet with commentary
TWEET_ID=$(twitter search "interesting topic" --max 1 --json | jq -r '.data[0].id')
twitter quote "$TWEET_ID" "This is a great insight!"
Like all search results
twitter search "interesting topic" --max 5 --json | jq -r '.data[].id' | while read id; do
twitter like "$id"
done
Get user info then follow
twitter user targethandle --json | jq '.data | {username, followers, bio}'
twitter follow targethandle
Find most popular tweets from a user
twitter user-posts elonmusk --max 20 --json | jq '.data | sort_by(.metrics.likes) | reverse | .[:3] | .[] | {id, text: .text[:80], likes: .metrics.likes}'
Check follower relationship
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"
Daily reading workflow
# 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
Search with jq filtering
# 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'
Ranking Filter
Filtering is opt-in. Enable with --filter:
twitter feed --filter
twitter bookmarks --filter
Error Reference
| Error | Cause | Fix |
|---|---|---|
No Twitter cookies found |
Not authenticated | Login to x.com in browser, or set env vars |
| HTTP 226 | Automated detection | Use browser cookie extraction (not env vars) |
| HTTP 401/403 | Cookie expired | Re-login to x.com and retry |
| HTTP 404 | QueryId rotation | Retry (auto-fallback built in) |
| HTTP 429 | Rate limited | Wait 15+ minutes, then retry |
| Error 187 | Duplicate tweet | Change text content |
| Error 186 | Tweet too long | Keep under 280 chars |
Limitations
- Images only — video/GIF animation upload not yet supported (image upload supports JPEG/PNG/GIF/WebP)
- No DMs — no direct messaging
- No notifications — can't read notifications
- No polls — can't create polls
- Single account — one set of credentials at a time
- Likes are private — Twitter/X made all likes private since June 2024.
twitter likesonly works for your own account
Safety Notes
- Write operations have built-in random delays (1.5–4s) to avoid rate limits.
- TLS fingerprint and User-Agent are automatically matched to the Chrome version used.
- Do not ask users to share raw cookie values in chat logs.
- Prefer local browser cookie extraction over manual secret copy/paste.
- Agent should treat cookie values as secrets (do not echo to stdout unnecessarily).
04 同仓库更多 Skills
blocked-page-recovery
Use when a fetch fails: 403/429, paywall, WAF, bot wall.
gemini-vision-fallback
Vision fallback: Gemini REST API if vision_analyze blocked.
prism-scan
Structural analysis through dynamically generated cognitive lenses. Generates the optimal analytical lens for the specific code/artifact, then executes it. Finds conservation laws, structural invariants, and concrete bugs that vanilla analysis misses. Use on any code file, system design, or text artifact.
prism-reflect
Constraint transparency: analyzes an artifact structurally, then analyzes what its own analysis concealed. Produces a conservation law AND a constraint report showing what was maximized, what was sacrificed, and what to investigate next. The only AI skill that knows what it can't see.
prism-full
Full Prism: multi-pass structural analysis with mandatory adversarial self-correction. Designs custom analytical passes, executes them with chaining, then attacks its own findings before synthesizing. Use for maximum depth on important code or artifacts.
prism-discover
Discover all possible analysis domains for an artifact. Finds obvious and non-obvious angles — architecture, security, but also marketing positioning, user psychology, regulatory implications, teaching value. Use before prism-scan or prism-full to explore what's worth investigating.