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

• 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