Skill: jackwener/twitter-cli (version 0.5.1)

--- name: twitter-cli 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. author: jackwener version: "2.0.0" tags: - twitter - x - social-media - terminal - cli --- # twitter-cli — Twitter/X CLI Tool **Binary:** `twitter` **Credentials:** browser cookies (auto-extracted) or env vars ## Setup ```bash # Install (requires Python 3.8+) uv tool install twitter-cli # Or: pipx install 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 ```bash twitter status --yaml >/dev/null && echo "AUTH_OK" || echo "AUTH_NEEDED" ``` If `AUTH_OK`, skip to [Command Reference](#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. ```bash twitter whoami ``` **Method B: Environment variables** ```bash 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 登录凭证。请按以下步骤获取： > > 1. 用 Chrome/Edge/Firefox 打开 https://x.com（确保已登录） > 2. 按 `F12` 打开开发者工具 → **Network** 标签 > 3. 在页面上刷新，点击任意 `x.com` 请求 > 4. 找到 **Request Headers** → **Cookie:** 这一行，右键 → 复制值 > 5. 把完整 Cookie 字符串发给我 > > ⚠️ Cookie 包含登录信息，请不要分享给其他人。 Then extract and set env vars: ```bash 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) ```bash twitter feed # Pretty table output ``` ### YAML / JSON: structured output Non-TTY stdout defaults to YAML automatically. Use `OUTPUT=yaml|json|rich|auto` to override. ```bash twitter feed --yaml twitter feed --json | jq '.[0].text' ``` All machine-readable output uses the envelope documented in [SCHEMA.md](./SCHEMA.md). Tweet and user payloads now live under `.data`. ### Compact: `-c` flag (minimal tokens for LLM) ```bash 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 ```bash 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 --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 --max 30 --yaml twitter search "keyword" # Search tweets twitter search "AI agent" -t Latest --max 50 twitter search "topic" -o results.json # Save to file twitter tweet 1234567890 # Tweet detail + replies twitter tweet https://x.com/user/status/12345 # Accepts URL twitter list 1539453138322673664 # List timeline twitter user-posts elonmusk --max 20 # User's tweets twitter likes elonmusk --max 30 # User's likes twitter followers elonmusk --max 50 # Followers twitter following elonmusk --max 50 # Following ``` ### Write Operations ```bash twitter post "Hello from twitter-cli!" # Post tweet twitter reply 1234567890 "Great tweet!" # Reply (standalone) twitter post "reply text" --reply-to 1234567890 # Reply (via post) twitter quote 1234567890 "Interesting take" # Quote-tweet 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 ``` ## Agent Workflows ### Post and verify ```bash twitter post "My tweet text" 2>/dev/null # Output includes tweet URL: 🔗 https://x.com/i/status/<id> ``` ### Reply to someone's latest tweet ```bash TWEET_ID=$(twitter user-posts targetuser --max 1 --json | jq -r '.data[0].id') twitter reply "$TWEET_ID" "Nice post!" ``` ### Create a thread ```bash # 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 ```bash 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 ```bash twitter search "interesting topic" --max 5 --json | jq -r '.data[].id' | while read id; do twitter like "$id" done ``` ### Get user info then follow ```bash twitter user targethandle --json | jq '.data | {username, followers, bio}' twitter follow targethandle ``` ### Find most popular tweets from a user ```bash 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 ```bash 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 ```bash # Compact mode for token-efficient LLM context twitter -c feed -t following --max 30 twitter -c bookmarks --max 20 # Full JSON for analysis twitter feed -t following --max 30 -o following.json twitter bookmarks --max 20 -o bookmarks.json ``` ### Search with jq filtering ```bash # 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`: ```bash 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 - **Text only** — no media/image upload - **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 ## 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).


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal:  | SkillSpector: suspicious (CRITICAL)