OpenSkillIndex← back to search
claude-codeopenclawdata

Skills x-ads-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-ads-cli" ~/.claude/skills/openclaw-skills-x-ads-cli && rm -rf "$T"
OpenClaw · Install into ~/.openclaw/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openclaw/skills "$T" && mkdir -p ~/.openclaw/skills && cp -r "$T/skills/bin-huang/x-ads-cli" ~/.openclaw/skills/openclaw-skills-x-ads-cli && rm -rf "$T"
manifest: skills/bin-huang/x-ads-cli/SKILL.md
tags
#cli#twitter-ads#data-analysis#api-integration#reporting
source content

X Ads CLI Skill

You have access to 

x-ads-cli
, a read-only CLI for the X Ads API (v12). Use it to query ad accounts, pull synchronous analytics, inspect promoted tweets and media creatives, review targeting criteria, check funding instruments, and estimate reach. Handles OAuth 1.0a signing natively with Node.js 
crypto
-- no external dependencies.

Quick start

# Check if the CLI is available
x-ads-cli --help

# List all accessible ad accounts
x-ads-cli accounts

# Get a specific ad account
x-ads-cli account abc1x2

If the CLI is not installed, install it:

npm install -g x-ads-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_ADS_API_KEY
    , 
    X_ADS_API_SECRET
    , 
    X_ADS_ACCESS_TOKEN
    , 
    X_ADS_ACCESS_TOKEN_SECRET
  3. Auto-detected file: 
    ~/.config/x-ads-cli/credentials.json

The credentials file format:

{
  "api_key": "YOUR_API_KEY",
  "api_secret": "YOUR_API_SECRET",
  "access_token": "YOUR_ACCESS_TOKEN",
  "access_token_secret": "YOUR_ACCESS_TOKEN_SECRET"
}

The Access Token must belong to a user who has access to at least one X Ads account. Ads API access requires separate approval from the X Developer Portal.

Before running any command, verify credentials are configured by running 

x-ads-cli accounts
. If it fails with a credentials error, ask the user to set up authentication.

Entity hierarchy

Ad Account
 +-- Campaign
 |    +-- Line Item (ad group)
 |         +-- Promoted Tweet
 |         +-- Targeting Criteria
 +-- Media Creative
 +-- Card (website, app install, etc.)
 +-- Custom Audience
 +-- Funding Instrument (payment method)
 +-- Conversion Event (web event tag)

Line items sit under campaigns and contain targeting, budget, and bid settings. Promoted tweets are attached to line items.

Monetary values

The X Ads API returns monetary values (e.g., 

billed_charge_local_micro
) in microcurrency -- the value multiplied by 1,000,000. Divide by 1,000,000 to get the actual amount in the major currency unit. For example, 
5000000
means $5.00.

Output format

All commands output pretty-printed JSON by default. Use 

--format compact
for single-line JSON (useful for piping).

Pagination for listing commands uses cursor-based 

--cursor
values from the 
next_cursor
field in the response.

Commands reference

Account discovery

# List all accessible ad accounts
x-ads-cli accounts

# Include deleted accounts
x-ads-cli accounts --with-deleted

# Get a specific ad account
x-ads-cli account abc1x2

accounts options:

  • --with-deleted
    -- include deleted accounts

account takes a single required argument: the account ID.

Campaigns

# List all campaigns for an account
x-ads-cli campaigns abc1x2

# Filter by specific campaign IDs
x-ads-cli campaigns abc1x2 --campaign-ids id1,id2

# Include deleted campaigns with custom page size
x-ads-cli campaigns abc1x2 --with-deleted --count 500

# Paginate
x-ads-cli campaigns abc1x2 --cursor next_cursor_value

Options:

  • --campaign-ids <ids>
    -- filter by campaign IDs (comma-separated)
  • --with-deleted
    -- include deleted campaigns
  • --count <n>
    -- results per page (default 200, max 1000)
  • --cursor <cursor>
    -- pagination cursor from previous response

Line items

# List all line items for an account
x-ads-cli line-items abc1x2

# Filter by campaign
x-ads-cli line-items abc1x2 --campaign-ids campaign_id_1

# Filter by specific line item IDs
x-ads-cli line-items abc1x2 --line-item-ids li1,li2

# Include deleted, with pagination
x-ads-cli line-items abc1x2 --with-deleted --cursor next_cursor_value

Options:

  • --campaign-ids <ids>
    -- filter by campaign IDs (comma-separated)
  • --line-item-ids <ids>
    -- filter by line item IDs (comma-separated)
  • --with-deleted
    -- include deleted line items
  • --count <n>
    -- results per page (default 200, max 1000)
  • --cursor <cursor>
    -- pagination cursor

Analytics (stats)

The 

stats
command provides synchronous analytics. Supports up to 7 days of data per request.

# Campaign-level daily metrics
x-ads-cli stats abc1x2 \
  --entity CAMPAIGN \
  --entity-ids campaign_id_1,campaign_id_2 \
  --start-time 2026-03-01T00:00:00Z \
  --end-time 2026-03-07T00:00:00Z \
  --granularity DAY \
  --metric-groups ENGAGEMENT,BILLING

# Line item hourly metrics with video
x-ads-cli stats abc1x2 \
  --entity LINE_ITEM \
  --entity-ids line_item_id_1 \
  --start-time 2026-03-15T00:00:00Z \
  --end-time 2026-03-16T00:00:00Z \
  --granularity HOUR \
  --metric-groups ENGAGEMENT,BILLING,VIDEO

# Promoted tweet total metrics
x-ads-cli stats abc1x2 \
  --entity PROMOTED_TWEET \
  --entity-ids pt_id_1 \
  --start-time 2026-03-01T00:00:00Z \
  --end-time 2026-03-07T00:00:00Z \
  --granularity TOTAL \
  --metric-groups ENGAGEMENT,BILLING

Required options:

  • --entity <type>
    -- entity type (required). Values: 
    CAMPAIGN
    , 
    LINE_ITEM
    , 
    PROMOTED_TWEET
    , 
    MEDIA_CREATIVE
    , 
    FUNDING_INSTRUMENT
    , 
    ORGANIC_TWEET
  • --entity-ids <ids>
    -- entity IDs, comma-separated (required)
  • --start-time <time>
    -- ISO 8601 start time (required)
  • --end-time <time>
    -- ISO 8601 end time (required)

Optional:

  • --granularity <gran>
    -- 
    HOUR
    , 
    DAY
    , or 
    TOTAL
    (default 
    DAY
    )
  • --metric-groups <groups>
    -- comma-separated metric groups (default 
    ENGAGEMENT,BILLING
    ). Available: 
    ENGAGEMENT
    , 
    BILLING
    , 
    VIDEO
    , 
    MEDIA
    , 
    WEB_CONVERSION
    , 
    MOBILE_CONVERSION
    , 
    LIFE_TIME_VALUE_MOBILE_CONVERSION
  • --placement <placement>
    -- 
    ALL_ON_TWITTER
    , 
    PUBLISHER_NETWORK
    , 
    SPOTLIGHT
    , 
    TREND
    (default 
    ALL_ON_TWITTER
    )

The CLI passes 

--metric-groups
directly to the X Ads API, which returns the individual metrics for each group. Refer to the X Ads Analytics docs for the specific metrics included in each group.

Promoted tweets

# List promoted tweets for an account
x-ads-cli promoted-tweets abc1x2

# Filter by line item
x-ads-cli promoted-tweets abc1x2 --line-item-ids li1,li2

Options:

  • --line-item-ids <ids>
    -- filter by line item IDs (comma-separated)
  • --count <n>
    -- results per page (default 200)
  • --cursor <cursor>
    -- pagination cursor

Media creatives

# List media creatives for an account
x-ads-cli media-creatives abc1x2

Options:

  • --count <n>
    -- results per page (default 200)
  • --cursor <cursor>
    -- pagination cursor

Cards

# List all cards for an account
x-ads-cli cards abc1x2

# Filter by card types
x-ads-cli cards abc1x2 --card-types WEBSITE,VIDEO_WEBSITE

Options:

  • --card-types <types>
    -- filter by types (comma-separated). Values include: 
    WEBSITE
    , 
    VIDEO_WEBSITE
    , 
    IMAGE_APP_DOWNLOAD
    , etc.
  • --count <n>
    -- results per page (default 200)
  • --cursor <cursor>
    -- pagination cursor

Targeting criteria

# List targeting criteria for an account
x-ads-cli targeting-criteria abc1x2

# Filter by line items
x-ads-cli targeting-criteria abc1x2 --line-item-ids li1,li2

Options:

  • --line-item-ids <ids>
    -- filter by line item IDs (comma-separated)
  • --count <n>
    -- results per page (default 200)
  • --cursor <cursor>
    -- pagination cursor

Custom audiences

# List custom audiences for an account
x-ads-cli custom-audiences abc1x2

Options:

  • --count <n>
    -- results per page (default 200)
  • --cursor <cursor>
    -- pagination cursor

Funding instruments

# List funding instruments (payment methods) for an account
x-ads-cli funding-instruments abc1x2

Options:

  • --count <n>
    -- results per page (default 200)

Note: This command does not support 

--cursor
pagination.

Conversion events

# List web conversion events for an account
x-ads-cli conversion-events abc1x2

Options:

  • --count <n>
    -- results per page (default 200)

Note: This command does not support 

--cursor
pagination.

Reach estimate

# Get reach estimate for a line item
x-ads-cli reach-estimate abc1x2 --line-item-id li1

Required options:

  • --line-item-id <id>
    -- line item ID (required)

Workflow guidance

When the user asks for a quick overview

  1. Run 
    x-ads-cli accounts
    to find accessible accounts
  2. Use 
    campaigns
    to list active campaigns
  3. Use 
    stats
    with 
    --granularity TOTAL
    and 
    --metric-groups ENGAGEMENT,BILLING
    for a performance snapshot
  4. Monetary values from stats are in microcurrency -- divide by 1,000,000

When the user asks for deep analysis

  1. Start with 
    stats
    at the 
    CAMPAIGN
    entity level for an overview
  2. Drill into specific campaigns with 
    line-items
    to find their ad groups
  3. Use 
    stats
    at the 
    LINE_ITEM
    level for underperforming campaigns
  4. Use 
    --granularity HOUR
    for intraday trends or 
    --granularity DAY
    for multi-day trends
  5. Cross-reference with 
    promoted-tweets
    to inspect individual tweet performance
  6. Check 
    targeting-criteria
    to review targeting setup

When the user asks about creative performance

  1. Run 
    stats
    with 
    --entity PROMOTED_TWEET
    for promoted tweet metrics
  2. Use 
    promoted-tweets
    to list tweets and their IDs
  3. Use 
    media-creatives
    to inspect media assets
  4. Use 
    cards
    to review card-based creatives (website cards, app install cards)

When the user asks about audience reach

  1. Use 
    custom-audiences
    to see existing audiences
  2. Use 
    reach-estimate
    with a line item ID to get estimated reach
  3. Use 
    targeting-criteria
    to review what targeting is applied to line items

When the user asks about billing and spend

  1. Use 
    stats
    with 
    --metric-groups BILLING
    for billing data
  2. Use 
    funding-instruments
    to see payment methods on file
  3. Remember: monetary values are in microcurrency (divide by 1,000,000)

When the user asks about conversion tracking

  1. Use 
    conversion-events
    to list web event tags
  2. Use 
    stats
    with 
    --metric-groups WEB_CONVERSION
    or 
    MOBILE_CONVERSION
    for conversion data

Multi-day analytics

The stats command supports up to 7 days per request. For longer date ranges, make multiple requests with consecutive 7-day windows and combine the results.

Error handling

  • Authentication errors -- ask the user to verify their OAuth credentials (API Key, API Secret, Access Token, Access Token Secret) and that their app has Ads API access
  • No credentials found -- the CLI checked all three sources (flag, env vars, default file) and found nothing; ask the user to set up credentials
  • Empty results -- check that the account ID is correct, the entity exists, and (for stats) the date range contains active ad activity
  • HTTP 403 -- the authenticated user may not have access to the specified ad account
  • HTTP 429 -- rate limited; wait and retry
  • Stats date range too large -- the API supports max 7 days per request; split into smaller windows

API documentation references