Skills x-analytics-cli

install

source · Clone the upstream repo

git clone https://github.com/openclaw/skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/bin-huang/x-analytics-cli" ~/.claude/skills/clawdbot-skills-x-analytics-cli && rm -rf "$T"

manifest: skills/bin-huang/x-analytics-cli/SKILL.md

source content

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:

```
--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

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

Skills x-analytics-cli

X Analytics CLI Skill

Quick start

Authentication

Output format

Commands reference

User lookup

me

user

Tweet lookup

tweet

tweets

Search

search

tweet-counts

Timeline

timeline

Common field values

tweet-fields

user-fields

media-fields

expansions (for tweets)

expansions (for users)

Pagination

Workflow guidance

When the user asks about a user's profile or stats

When the user asks to search for tweets on a topic

When the user asks about tweet volume or trends

When the user asks about a specific tweet

When the user asks about their own tweets

When the user asks for a comprehensive analysis

Error handling

API documentation references