TikTok Ads CLI Skill

You have access to tiktok-ads-cli, a read-only CLI for the TikTok Marketing API (v1.3). Use it to query advertiser accounts, pull synchronous and async performance reports, inspect ad creatives and assets, manage custom and lookalike audiences, and check pixel tracking.

Quick start

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

# Get advertiser account info
tiktok-ads-cli advertiser 7000000000000

# List campaigns
tiktok-ads-cli campaigns 7000000000000

If the CLI is not installed, install it:

npm install -g tiktok-ads-cli

Authentication

The CLI requires a TikTok OAuth access token. Credentials are resolved in this order:

1. --credentials <path> flag (per-command)
2. Environment variable: TIKTOK_ADS_ACCESS_TOKEN (also reads TIKTOK_ADS_APP_ID and TIKTOK_ADS_SECRET if set)
3. Auto-detected file: ~/.config/tiktok-ads-cli/credentials.json

The credentials JSON file requires only access_token. The app_id and secret fields are optional:

{
  "access_token": "YOUR_ACCESS_TOKEN"
}

Before running any command, verify credentials are configured by running tiktok-ads-cli advertiser <id>. If it fails with a credentials error, ask the user to set up authentication.

Entity hierarchy

Advertiser Account
 +-- Campaign
 |    +-- Ad Group
 |         +-- Ad -> Creative
 +-- Custom Audience
 +-- Lookalike Audience
 +-- Pixel

Advertiser IDs are numeric strings (e.g., 7000000000000). Every command that operates on entities within an account takes the advertiser ID as its first positional argument.

Monetary values

The TikTok Marketing API returns monetary values (e.g., spend, cpc, cpm) as decimal strings in the major currency unit (e.g., "12.34" means $12.34). No conversion needed.

Output format

All commands output pretty-printed JSON by default. Use --format compact for single-line JSON (useful for piping).

Listing commands use page-based pagination with --page and --page-size options. Check the page_info object in the response for total_number, page, and total_page to determine if more pages exist.

Commands reference

Advertiser info

# Get advertiser account details (supports comma-separated IDs for multiple accounts)
tiktok-ads-cli advertiser 7000000000000
tiktok-ads-cli advertiser 7000000000000,7000000000001

Campaign hierarchy

# List campaigns
tiktok-ads-cli campaigns 7000000000000
tiktok-ads-cli campaigns 7000000000000 --status CAMPAIGN_STATUS_ENABLE
tiktok-ads-cli campaigns 7000000000000 --page 2 --page-size 50

# List ad groups
tiktok-ads-cli adgroups 7000000000000
tiktok-ads-cli adgroups 7000000000000 --campaign-ids 123,456
tiktok-ads-cli adgroups 7000000000000 --status ADGROUP_STATUS_DELIVERY_OK
tiktok-ads-cli adgroups 7000000000000 --campaign-ids 123 --status ADGROUP_STATUS_ENABLE