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