X Analytics CLI

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

# Check if the CLI is available
x-analytics-cli --help
Get the authenticated user's profile
x-analytics-cli me
Search recent tweets
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:

1. --credentials flag (per-command) 2. Environment variables: X_API_KEY, X_API_SECRET, X_ACCESS_TOKEN, X_ACCESS_TOKEN_SECRET 3. 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:

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

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:

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:

#### 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:

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:

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:

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:

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

1. Run x-analytics-cli user --user-fields public_metrics,description,created_at to get their profile and metrics 2. Present follower counts, tweet count, and account creation date

When the user asks to search for tweets on a topic

1. Run x-analytics-cli search "" --max-results 50 --tweet-fields public_metrics,created_at,author_id --expansions author_id --user-fields username 2. Adjust --sort-order relevancy if the user wants the most relevant results rather than the most recent 3. Use --next-token to paginate through more results if needed

When the user asks about tweet volume or trends

1. Run x-analytics-cli tweet-counts "" --granularity hour to see volume over time 2. Use --granularity minute for fine-grained analysis or --granularity day for a broader view 3. Narrow with --start-time and --end-time for a specific window 4. Compare multiple queries by running tweet-counts for each term

When the user asks about a specific tweet

1. Run x-analytics-cli tweet --tweet-fields public_metrics,created_at,author_id --expansions author_id --user-fields username to get the tweet with engagement metrics and author info 2. For multiple tweets, use x-analytics-cli tweets , with the same fields

When the user asks about their own tweets

1. Run x-analytics-cli timeline --max-results 50 --tweet-fields public_metrics,created_at to get recent tweets with engagement 2. Use --exclude retweets,replies to focus on original tweets only 3. Use --start-time and --end-time to narrow to a specific date range

When the user asks for a comprehensive analysis

1. Start with x-analytics-cli me --user-fields public_metrics to get the user's own stats 2. Use timeline with --tweet-fields public_metrics to analyze engagement on their tweets 3. Use search "from:" for a broader view of their recent output 4. Use tweet-counts "from:" --granularity day to see their posting frequency

Error handling

API documentation references

# Check if the CLI is available
x-analytics-cli --help
Get the authenticated user's profile
x-analytics-cli me
Search recent tweets
x-analytics-cli search "OpenAI"

If the CLI is not installed, install it:

npm install -g x-analytics-cli