| name | x-analytics-cli |
| description | X (Twitter) analytics and data retrieval via x-analytics-cli. Use when the user wants to search tweets, count tweet volumes, look up user profiles, get tweet details, or pull a user's timeline from X (formerly Twitter). Triggers: "X analytics", "Twitter analytics", "tweet search", "tweet lookup", "tweet counts", "X user profile", "Twitter user", "tweet timeline", "X API", "Twitter API", "search tweets", "tweet volume", "trending tweets", "X data", "Twitter data".
|
X Analytics CLI Skill
You have access to x-analytics-cli, a read-only CLI for the X API v2. Use it to search recent tweets, count tweet volumes over time, look up users and tweets by ID, and retrieve the authenticated user's timeline. All requests use OAuth 1.0a signing.
Quick start
x-analytics-cli --help
x-analytics-cli me
x-analytics-cli search "OpenAI"
If the CLI is not installed, install it:
npm install -g x-analytics-cli
Authentication
The CLI requires four OAuth 1.0a credentials: API Key, API Secret, Access Token, and Access Token Secret. Credentials are resolved in this order:
--credentials <path> flag (per-command)- Environment variables:
X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET
- Auto-detected file:
~/.config/x-analytics-cli/credentials.json
The credentials JSON file must contain these four fields:
{
"api_key": "...",
"api_secret": "...",
"access_token": "...",
"access_token_secret": "..."
}
API access tiers affect which commands are available:
- Free tier -- authenticated user lookup (
me)
- Basic or higher -- tweet lookup (
tweet, tweets), user lookup (user), search (search), tweet counts (tweet-counts), timelines (timeline)
Before running any command, verify credentials are configured by running x-analytics-cli me. If it fails with a credentials error, ask the user to set up authentication.
Output format
All commands output pretty-printed JSON by default. Use --format compact for single-line JSON (useful for piping). The only valid format values are json (default) and compact.
Errors are written to stderr as JSON with an error field and a non-zero exit code, e.g. {"error": "Unauthorized - Invalid or expired token"}.
The response shape follows the X API v2 convention: data (primary results), includes (expanded objects), and meta (pagination info). Not all fields are present in every response.
Commands reference
User lookup
me
Get the authenticated user's profile.
x-analytics-cli me
x-analytics-cli me --user-fields public_metrics,description,created_at
x-analytics-cli me --expansions pinned_tweet_id --tweet-fields created_at,public_metrics
Options:
--user-fields <fields> -- user fields to include--expansions <expansions> -- expansions to include--tweet-fields <fields> -- tweet fields to include (useful with expansions)
user
Get a user by username or numeric ID. Accepts usernames with or without the leading @. Numeric IDs are auto-detected and routed to the ID-based endpoint.
x-analytics-cli user elonmusk
x-analytics-cli user @elonmusk
x-analytics-cli user 44196397
x-analytics-cli user elonmusk --user-fields public_metrics,description,created_at
x-analytics-cli user elonmusk --expansions pinned_tweet_id --tweet-fields text
Options:
--user-fields <fields> -- user fields to include--expansions <expansions> -- expansions to include--tweet-fields <fields> -- tweet fields to include (useful with expansions)
Tweet lookup
tweet
Get a single tweet by ID.
x-analytics-cli tweet 1234567890
x-analytics-cli tweet 1234567890 --tweet-fields public_metrics,created_at,author_id
x-analytics-cli tweet 1234567890 --expansions author_id --user-fields username,name
Options:
--tweet-fields <fields> -- tweet fields to include--expansions <expansions> -- expansions to include--user-fields <fields> -- user fields to include--media-fields <fields> -- media fields to include--place-fields <fields> -- place fields to include--poll-fields <fields> -- poll fields to include
tweets
Get multiple tweets by IDs (comma-separated).
x-analytics-cli tweets 1234567890,9876543210
x-analytics-cli tweets 1234567890,9876543210 --tweet-fields public_metrics,created_at
x-analytics-cli tweets 1234567890,9876543210 --expansions author_id --user-fields username,name
Options:
--tweet-fields <fields> -- tweet fields to include--expansions <expansions> -- expansions to include--user-fields <fields> -- user fields to include--media-fields <fields> -- media fields to include--place-fields <fields> -- place fields to include--poll-fields <fields> -- poll fields to include
Search
search
Search recent tweets (last 7 days). Requires Basic API access or higher.
x-analytics-cli search "from:elonmusk"
x-analytics-cli search "OpenAI" --max-results 50 --sort-order relevancy
x-analytics-cli search "#AI" --start-time 2026-03-10T00:00:00Z --end-time 2026-03-17T00:00:00Z
x-analytics-cli search "lang:en bitcoin" --tweet-fields public_metrics,created_at,author_id --expansions author_id --user-fields username
Options:
--max-results <n> -- max results, 10-100--start-time <time> -- ISO 8601 start time--end-time <time> -- ISO 8601 end time--sort-order <order> -- recency or relevancy--next-token <token> -- pagination token from meta.next_token in the response--tweet-fields <fields> -- tweet fields to include--expansions <expansions> -- expansions to include--user-fields <fields> -- user fields to include--media-fields <fields> -- media fields to include--place-fields <fields> -- place fields to include--poll-fields <fields> -- poll fields to include
Supports the full X API v2 search query syntax: from:, to:, is:retweet, has:media, lang:, hashtags, mentions, boolean operators (OR, -), and more.
tweet-counts
Get tweet counts for a search query over time (last 7 days). Requires Basic API access or higher.
x-analytics-cli tweet-counts "OpenAI"
x-analytics-cli tweet-counts "#AI" --granularity hour
x-analytics-cli tweet-counts "from:elonmusk" --granularity day --start-time 2026-03-01T00:00:00Z
x-analytics-cli tweet-counts "bitcoin OR ethereum" --granularity minute --start-time 2026-03-18T00:00:00Z --end-time 2026-03-18T01:00:00Z
Options:
--granularity <g> -- minute, hour, or day (default: day)--start-time <time> -- ISO 8601 start time--end-time <time> -- ISO 8601 end time--next-token <token> -- pagination token from meta.next_token in the response
Returns an array of time-bucketed counts in data, plus meta.total_tweet_count for the total across all buckets.
Timeline
timeline
Get tweets posted by the authenticated user. Internally calls /users/me first to resolve the user ID, then fetches the timeline.
x-analytics-cli timeline
x-analytics-cli timeline --max-results 50
x-analytics-cli timeline --exclude retweets,replies
x-analytics-cli timeline --tweet-fields public_metrics,created_at --start-time 2026-03-01T00:00:00Z
x-analytics-cli timeline --max-results 20 --expansions author_id --user-fields username
Options:
--max-results <n> -- max results, 1-100--start-time <time> -- ISO 8601 start time--end-time <time> -- ISO 8601 end time--exclude <types> -- exclude types: retweets, replies (comma-separated)--next-token <token> -- pagination token from meta.next_token in the response--tweet-fields <fields> -- tweet fields to include--expansions <expansions> -- expansions to include--user-fields <fields> -- user fields to include--media-fields <fields> -- media fields to include--place-fields <fields> -- place fields to include--poll-fields <fields> -- poll fields to include
Common field values
tweet-fields
attachments, author_id, context_annotations, conversation_id, created_at, edit_controls, edit_history_tweet_ids, entities, geo, id, in_reply_to_user_id, lang, public_metrics, possibly_sensitive, referenced_tweets, reply_settings, source, text, withheld
The public_metrics object contains: retweet_count, reply_count, like_count, quote_count, bookmark_count, impression_count.
user-fields
created_at, description, entities, id, location, most_recent_tweet_id, name, pinned_tweet_id, profile_image_url, protected, public_metrics, url, username, verified, verified_type, withheld
The public_metrics object contains: followers_count, following_count, tweet_count, listed_count.
media-fields
duration_ms, height, media_key, preview_image_url, public_metrics, type, url, width, alt_text, variants
expansions (for tweets)
author_id, referenced_tweets.id, in_reply_to_user_id, attachments.media_keys, attachments.poll_ids, geo.place_id, entities.mentions.username, referenced_tweets.id.author_id, edit_history_tweet_ids
expansions (for users)
pinned_tweet_id
Pagination
The search, tweet-counts, and timeline commands support pagination via --next-token. When a response includes meta.next_token, pass that value to the next call to fetch the next page. The me, user, tweet, and tweets commands do not paginate.
Workflow guidance
When the user asks about a user's profile or stats
- Run
x-analytics-cli user <username> --user-fields public_metrics,description,created_at to get their profile and metrics
- Present follower counts, tweet count, and account creation date
When the user asks to search for tweets on a topic
- Run
x-analytics-cli search "<query>" --max-results 50 --tweet-fields public_metrics,created_at,author_id --expansions author_id --user-fields username
- Adjust
--sort-order relevancy if the user wants the most relevant results rather than the most recent
- Use
--next-token to paginate through more results if needed
When the user asks about tweet volume or trends
- Run
x-analytics-cli tweet-counts "<query>" --granularity hour to see volume over time
- Use
--granularity minute for fine-grained analysis or --granularity day for a broader view
- Narrow with
--start-time and --end-time for a specific window
- Compare multiple queries by running
tweet-counts for each term
When the user asks about a specific tweet
- Run
x-analytics-cli tweet <id> --tweet-fields public_metrics,created_at,author_id --expansions author_id --user-fields username to get the tweet with engagement metrics and author info
- For multiple tweets, use
x-analytics-cli tweets <id1>,<id2> with the same fields
When the user asks about their own tweets
- Run
x-analytics-cli timeline --max-results 50 --tweet-fields public_metrics,created_at to get recent tweets with engagement
- Use
--exclude retweets,replies to focus on original tweets only
- Use
--start-time and --end-time to narrow to a specific date range
When the user asks for a comprehensive analysis
- Start with
x-analytics-cli me --user-fields public_metrics to get the user's own stats
- Use
timeline with --tweet-fields public_metrics to analyze engagement on their tweets
- Use
search "from:<username>" for a broader view of their recent output
- Use
tweet-counts "from:<username>" --granularity day to see their posting frequency
Error handling
- "No credentials found" -- ask the user to set up authentication via credentials file, environment variables, or
--credentials flag
- "Unauthorized" -- the access token is invalid or expired; ask the user to regenerate tokens in the X Developer Portal
- "Forbidden" / 403 -- the API access tier may not support the endpoint (e.g., search requires Basic tier)
- Empty data -- the query returned no results; check the search query syntax, date range, or whether the user/tweet exists
- Rate limit errors -- the X API has per-endpoint rate limits; wait and retry, or reduce request frequency
API documentation references
