OpenSkillIndex← back to search
claude-codeopenclawmarketing

Skills tiktok-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/tiktok-ads-cli" ~/.claude/skills/openclaw-skills-tiktok-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/tiktok-ads-cli" ~/.openclaw/skills/openclaw-skills-tiktok-ads-cli && rm -rf "$T"
manifest: skills/bin-huang/tiktok-ads-cli/SKILL.md
tags
#tiktok-ads#api#reporting#data-analysis#cli#marketing
source content

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

# List ads
tiktok-ads-cli ads 7000000000000
tiktok-ads-cli ads 7000000000000 --campaign-ids 123,456
tiktok-ads-cli ads 7000000000000 --adgroup-ids 789
tiktok-ads-cli ads 7000000000000 --status AD_STATUS_DELIVERY_OK
tiktok-ads-cli ads 7000000000000 --campaign-ids 123 --adgroup-ids 789 --status AD_STATUS_ENABLE

campaigns options

OptionDescriptionDefault
--status <status>
Filter by primary status (e.g., 
CAMPAIGN_STATUS_ENABLE
, 
CAMPAIGN_STATUS_DISABLE
)		all
--page <n>
Page number
1
--page-size <n>
Page size (max 1000)
100

adgroups options

OptionDescriptionDefault
--campaign-ids <ids>
Filter by campaign IDs (comma-separated)all
--status <status>
Filter by primary statusall
--page <n>
Page number
1
--page-size <n>
Page size (max 1000)
100

ads options

OptionDescriptionDefault
--campaign-ids <ids>
Filter by campaign IDs (comma-separated)all
--adgroup-ids <ids>
Filter by ad group IDs (comma-separated)all
--status <status>
Filter by primary statusall
--page <n>
Page number
1
--page-size <n>
Page size (max 1000)
100

Synchronous report

The 

report
command is the primary tool for performance analysis. All options marked required must be provided.

# Campaign-level daily report
tiktok-ads-cli report 7000000000000 \
  --report-type BASIC \
  --data-level AUCTION_CAMPAIGN \
  --dimensions campaign_id,stat_time_day \
  --metrics spend,impressions,clicks,ctr,cpc \
  --start-date 2026-03-01 \
  --end-date 2026-03-15

# Ad-level report
tiktok-ads-cli report 7000000000000 \
  --report-type BASIC \
  --data-level AUCTION_AD \
  --dimensions ad_id,stat_time_day \
  --metrics spend,impressions,clicks,conversion,cost_per_conversion \
  --start-date 2026-03-01 \
  --end-date 2026-03-15

# With filtering
tiktok-ads-cli report 7000000000000 \
  --report-type BASIC \
  --data-level AUCTION_CAMPAIGN \
  --dimensions campaign_id \
  --metrics spend,impressions \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --filters '[{"field_name":"campaign_ids","filter_type":"IN","filter_value":"123,456"}]'

report options

OptionRequiredDescriptionDefault
--report-type <type>
yes
BASIC
, 
AUDIENCE
, 
PLAYABLE_MATERIAL
, 
CATALOG
--
--data-level <level>
yes
AUCTION_ADVERTISER
, 
AUCTION_CAMPAIGN
, 
AUCTION_ADGROUP
, 
AUCTION_AD
--
--dimensions <dims>
yesComma-separated (e.g., 
campaign_id,stat_time_day
)		--
--metrics <metrics>
yesComma-separated (e.g., 
spend,impressions,clicks,ctr,cpc
)		--
--start-date <date>
yesStart date (
YYYY-MM-DD
)		--
--end-date <date>
yesEnd date (
YYYY-MM-DD
)		--
--filters <json>
noFiltering conditions as JSON stringnone
--page <n>
noPage number
1
--page-size <n>
noPage size (max 1000)
100

Common dimensions

Dimensions documented in CLI help text: 

ad_id
, 
adgroup_id
, 
campaign_id
, 
stat_time_day
, 
stat_time_hour
, 
country_code

The CLI passes dimension names directly to the TikTok Business API without validation. Audience dimensions (e.g., 

gender
, 
age
) are used with 
--report-type AUDIENCE
.

Common metrics

Metrics documented in CLI help text: 

spend
, 
impressions
, 
clicks
, 
ctr
, 
cpc
, 
cpm
, 
conversion
, 
cost_per_conversion

The CLI passes metric names directly to the TikTok Business API without validation. Refer to the TikTok Marketing API docs for the full list of available metrics (e.g., video engagement, ROAS, social interaction metrics).

Async report

For large reports, create an async task and check its status later.

# Create async report task
tiktok-ads-cli async-report 7000000000000 \
  --report-type BASIC \
  --dimensions ad_id,stat_time_day \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --metrics spend,impressions,clicks

# Check task status (poll until complete; returns download URL when done)
tiktok-ads-cli report-status 7000000000000 task_abc123

async-report options

OptionRequiredDescription
--report-type <type>
yes
BASIC
, 
AUDIENCE
, 
PLAYABLE
--dimensions <dims>
yesComma-separated dimension names
--start-date <date>
yesStart date (
YYYY-MM-DD
)
--end-date <date>
yesEnd date (
YYYY-MM-DD
)
--metrics <metrics>
noComma-separated metric names

Note: The async report always uses 

data_level: AUCTION_AD
internally.

Audience report

# Audience analysis by gender and age
tiktok-ads-cli audience-report 7000000000000 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --dimensions gender,age

# Audience report filtered by campaigns
tiktok-ads-cli audience-report 7000000000000 \
  --start-date 2026-03-01 \
  --end-date 2026-03-15 \
  --dimensions gender,age \
  --campaign-ids 123,456

audience-report options

OptionRequiredDescription
--start-date <date>
yesStart date (
YYYY-MM-DD
)
--end-date <date>
yesEnd date (
YYYY-MM-DD
)
--dimensions <dims>
noDimensions: 
gender
, 
age
, 
country_code
, 
language
, 
platform
, etc.
--campaign-ids <ids>
noFilter by campaign IDs (comma-separated)

Creative assets

# List image assets
tiktok-ads-cli images 7000000000000
tiktok-ads-cli images 7000000000000 --page 2 --page-size 50

# List video assets
tiktok-ads-cli videos 7000000000000
tiktok-ads-cli videos 7000000000000 --page 2 --page-size 50

# List ad creatives (creative details for ads)
tiktok-ads-cli ad-creatives 7000000000000
tiktok-ads-cli ad-creatives 7000000000000 --ad-ids 123,456

images / videos options

OptionDescriptionDefault
--page <n>
Page number
1
--page-size <n>
Page size (max 1000)
100

ad-creatives options

OptionDescriptionDefault
--ad-ids <ids>
Filter by ad IDs (comma-separated)all
--page <n>
Page number
1
--page-size <n>
Page size
100

Audiences

# List custom audiences
tiktok-ads-cli custom-audiences 7000000000000
tiktok-ads-cli custom-audiences 7000000000000 --page 2 --page-size 50

# List lookalike audiences (a type of custom audience)
tiktok-ads-cli lookalike-audiences 7000000000000
tiktok-ads-cli lookalike-audiences 7000000000000 --page 2 --page-size 50

custom-audiences / lookalike-audiences options

OptionDescriptionDefault
--page <n>
Page number
1
--page-size <n>
Page size
100

Pixels

# List all pixels
tiktok-ads-cli pixels 7000000000000
tiktok-ads-cli pixels 7000000000000 --page 2

# Get a specific pixel by code
tiktok-ads-cli pixel 7000000000000 PIXEL_CODE_123

pixels options

OptionDescriptionDefault
--page <n>
Page number
1
--page-size <n>
Page size
100

The 

pixel
command takes no additional options -- just the advertiser ID and the pixel code.

Workflow guidance

When the user asks for a quick overview

  1. Run 
    tiktok-ads-cli campaigns <advertiser-id>
    to see all campaigns
  2. Use 
    tiktok-ads-cli report
    with 
    --report-type BASIC --data-level AUCTION_CAMPAIGN
    for a performance snapshot
  3. Present the data (report 
    spend
    is already in major currency units, no conversion needed)

When the user asks for deep analysis

  1. Start with a campaign-level report to see overall performance
  2. Use 
    --data-level AUCTION_ADGROUP
    to identify top/bottom ad groups
  3. Drill down with 
    --data-level AUCTION_AD
    for underperforming ad groups
  4. Use 
    audience-report
    with 
    --dimensions gender,age
    for demographic analysis
  5. Use 
    --dimensions stat_time_day
    for daily trends to spot anomalies
  6. Cross-reference with 
    ad-creatives
    to review creative content

When the user asks about creative performance

  1. Run a report with 
    --data-level AUCTION_AD
    to get ad-level metrics
  2. Use 
    ads
    to list ads and find their IDs
  3. Use 
    ad-creatives
    to inspect creative details
  4. Use 
    images
    and 
    videos
    to browse available creative assets

When the user asks about audience reach

  1. Use 
    custom-audiences
    to see existing custom audiences
  2. Use 
    lookalike-audiences
    to check lookalike audience setups
  3. Use 
    audience-report
    with demographic dimensions to see who is being reached

When the user asks about conversion tracking

  1. Run 
    pixels
    to list active TikTok Pixels
  2. Use 
    pixel
    to get details about a specific pixel
  3. Check the report with 
    conversions
    and 
    cost_per_conversion
    metrics

When the user asks for large date-range reports

  1. Use 
    async-report
    to create an async task (avoids timeout for large datasets)
  2. Use 
    report-status
    to poll for completion
  3. The completed task response will include a download URL

Error handling

  • Authentication errors -- ask the user to verify their access token; run 
    tiktok-ads-cli advertiser <id>
    to test
  • "No credentials found" -- ask the user to set up one of: 
    --credentials
    flag, 
    TIKTOK_ADS_ACCESS_TOKEN
    env var, or 
    ~/.config/tiktok-ads-cli/credentials.json
  • Empty report results -- check the date range, data level, and whether the account had active ads in the period
  • API error codes -- the CLI surfaces the TikTok API error message; common issues include invalid advertiser IDs, expired tokens, or insufficient permissions
  • Page out of range -- check 
    page_info.total_page
    in the response to avoid requesting pages beyond the total

API documentation references