| name | twx |
| description | Fetch and analyze Twitter/X data using the twx CLI tool. Use when the user wants to: (1) Analyze a Twitter user's tweets, timeline, or posting patterns, (2) Fetch a conversation thread or replies to a tweet, (3) Search Twitter for tweets matching a query, (4) Research Twitter accounts or topics, (5) Fetch retweeters or quote tweets for a tweet, (6) Any task involving Twitter/X data extraction. Triggers on mentions of Twitter, X, tweets, threads, timelines, tweet search, retweets, quotes, or Twitter usernames/URLs. |
twx — Twitter/X Data Extraction
Globally installed CLI tool that fetches tweets, threads, timelines, replies, and search results from Twitter/X via RapidAPI.
Setup Check
Before running any command, check auth status:
twx auth
If twx is not found, tell the user to install it:
npm install -g github:vicnaum/vics-twitter-toolkit
If no API key is found, ask the user to provide their RapidAPI key, then run:
twx auth <key>
The user needs a RapidAPI subscription to one or both of:
Running Commands
Always use -f json for analysis tasks (structured data). Use -f md for human-readable output. Use -o /tmp/twx or another temp dir to avoid polluting the project directory.
Global flag: -p (print to terminal)
Add -p before the command to print output to stdout instead of writing files. Useful for quick lookups or when piping output:
twx -p profile solana
twx -p search "bitcoin" --limit 5 -f json
When -p is used with -f both, markdown is printed.
Fetch User Profile
twx profile solana -f json -o /tmp/twx
twx profile @elonmusk -f json -o /tmp/twx
twx profile "https://x.com/levelsio" -f json -o /tmp/twx
Flags: -f json|md|both, -o <dir>, --debug
Returns: bio, location, website, follower/following counts, tweet/media/like counts, verification status, pinned tweet IDs, profile image shape.
JSON output structure for profiles:
{"id":"...","handle":"...","name":"...","bio":"...","location":"...","website":"...","followerCount":0,"followingCount":0,"tweetCount":0,"mediaCount":0,"likeCount":0,"isVerified":false,"verifiedType":null,"pinnedTweetIds":[],"profileImageShape":"Circle"}
Fetch User Timeline
twx user-tweets elonmusk --limit 50 -f json -o /tmp/twx
twx user-tweets @elonmusk --from 2024-01-01 --to 2024-06-30 -f json -o /tmp/twx
twx user-tweets "https://x.com/elonmusk" --include-replies --limit 200 -f json -o /tmp/twx
Flags: -l/--limit <n> (0=unlimited, default 100), --from/--to <YYYY-MM-DD>, --include-replies, -f json|md|both, -o <dir>
Fetch User Replies Only
twx user-replies elonmusk --limit 50 -f json -o /tmp/twx
Same flags as user-tweets (minus --include-replies).
Search Tweets
twx search "bitcoin" --limit 50 -f json -o /tmp/twx
twx search "from:elonmusk" --limit 50 --sort top -f json -o /tmp/twx
twx search "bitcoin min_faves:100 since:2024-01-01" --sort top -f json -o /tmp/twx
Flags: -l/--limit <n>, -s/--sort top|recent, -f json|md|both, -o <dir>
Search operators — combine freely in the query string:
| Operator | Example | Description |
|---|
"exact phrase" | "to the moon" | Exact phrase match |
OR | bitcoin OR ethereum | Match either term |
-word | bitcoin -scam | Exclude word |
from: | from:elonmusk | Tweets by user |
to: | to:elonmusk | Replies to user |
@mention | @elonmusk | Mentions of user |
filter:links | bitcoin filter:links | Only tweets with links |
filter:images | cats filter:images | Only tweets with images |
filter:videos | tutorial filter:videos | Only tweets with videos |
-filter:replies | from:elonmusk -filter:replies | Exclude replies |
min_faves: | bitcoin min_faves:100 | Minimum likes |
min_retweets: | bitcoin min_retweets:50 | Minimum retweets |
min_replies: | bitcoin min_replies:10 | Minimum replies |
since: | since:2024-01-01 | Tweets after date |
until: | until:2024-06-30 | Tweets before date |
lang: | bitcoin lang:en | Language filter |
conversation_id: | conversation_id:123456 | Tweets in a conversation |
-is:retweet | from:elonmusk -is:retweet | Exclude retweets |
Fetch Conversation Thread
twx thread 2019212107020136611 -f json -o /tmp/twx
twx thread "https://x.com/user/status/2019212107020136611" -f json -o /tmp/twx
Flags: --no-quotes, --detail-max-pages <n>, --search-max-pages <n>, --concurrency <n>, -f json|md|both, -o <dir>
Fetch Retweeters of a Tweet
twx retweeters 2029579972688379928 -f json -o /tmp/twx
twx retweeters "https://x.com/user/status/2029579972688379928" -f json -o /tmp/twx
Flags: --max-pages <n> (default 50), --debug, -f json|md|both, -o <dir>
Returns list of users who retweeted, with handle, name, bio, follower/following counts, verified status.
Fetch Quote Tweets
twx quotes 2029579972688379928 -f json -o /tmp/twx
twx quotes "https://x.com/user/status/2029579972688379928" -f json -o /tmp/twx
Flags: --max-pages <n> (default 50), --debug, -f json|md|both, -o <dir>
Returns tweets that quoted the given tweet, with full tweet data (text, author, engagement counts).
Note on Likers
The TweetFavoriters API endpoint does NOT work — Twitter made likes private in 2024, so the API returns empty. To get likers, you'd need to capture a HAR file from the browser while scrolling the likes panel (requires being logged in).
Input Formats
All commands accept flexible input:
- Usernames:
elonmusk, @elonmusk, https://x.com/elonmusk
- Tweet IDs:
2019212107020136611, https://x.com/user/status/2019212107020136611
Analysis Workflow
- Fetch data with
-f json to get structured output
- Read the JSON output file to analyze the data
- Present findings to the user
JSON output structure for timelines/search:
{"username":"...","tweets":[{"id":"...","text":"...","createdAt":"...","author":{"handle":"...","name":"..."},"replyCount":0,"favoriteCount":0,"retweetCount":0,"viewCount":0}],"stats":{...}}
JSON output structure for profiles:
{"id":"...","handle":"...","name":"...","bio":"...","followerCount":0,"followingCount":0,"tweetCount":0,"isVerified":false}
JSON output structure for threads:
{"root":{"id":"...","text":"...","author":{...},"children":[...]},"stats":{"totalTweets":50,"danglingParents":1}}
JSON output structure for retweeters:
{"tweetId":"...","type":"retweeters","stats":{"totalUsers":71,"pagesFetched":2},"users":[{"id":"...","handle":"...","name":"...","bio":"...","followerCount":0,"followingCount":0,"isVerified":false,"avatarUrl":"..."}]}
JSON output structure for quotes:
{"tweetId":"...","stats":{"totalTweets":32,"pagesFetched":3},"tweets":[{"id":"...","text":"...","createdAt":"...","author":{"handle":"...","name":"..."},"favoriteCount":0,"retweetCount":0,"viewCount":0}]}
Error Handling
- No API key: Ask user for their RapidAPI key, run
twx auth <key>
- Rate limiting: The tool has built-in retry with exponential backoff. If persistent 429 errors, reduce
--limit or wait
- Empty results: Check username spelling, try broader search terms, verify date ranges
