Apple Ads CLI Skill

You have access to apple-ads-cli, a read-only CLI for the Apple Search Ads Campaign Management API (v5). Use it to query campaigns, ad groups, ads, keywords, budget orders, pull performance reports, and check app eligibility on the App Store.

Quick start

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

# Get authenticated user info
apple-ads-cli me

# Get access control list (find your orgId)
apple-ads-cli acl

If the CLI is not installed, install it:

npm install -g apple-ads-cli

Authentication

The CLI requires an OAuth2 access token and an organization ID. Credentials are resolved in this order:

1. --credentials <path> flag (per-command)
2. Environment variables: APPLE_ADS_ACCESS_TOKEN + APPLE_ADS_ORG_ID
3. Auto-detected file: ~/.config/apple-ads-cli/credentials.json

The credentials JSON file must contain access_token and org_id fields. The access token is obtained by signing a JWT with your private key (ES256) and exchanging it at Apple's OAuth endpoint. Tokens expire after 1 hour.

Before running any command, verify credentials are configured by running apple-ads-cli me. If it fails with a credentials error, ask the user to set up authentication.

Entity hierarchy

Organization (orgId)
 +-- Campaign
 |    +-- Ad Group
 |         +-- Ad
 |         +-- Targeting Keyword
 |         +-- Negative Keyword
 |    +-- Campaign-level Negative Keyword
 +-- Budget Order
 +-- App (by Adam ID)

Organization IDs are numeric identifiers shown in the Apple Search Ads UI. The acl command returns all organizations the user has access to.

Monetary values

The Apple Search Ads API returns monetary values as objects with amount (string) and currency (string) fields, e.g. {"amount": "12.34", "currency": "USD"}. The amount is in the major currency unit -- no conversion needed.

Output format

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

All listing commands support --limit <n> (default 20) and --offset <n> (default 0) for pagination. Single-entity commands (me, acl, campaign, budget-order, app, app-eligibility) do not support pagination.

Commands reference

Account discovery

# Access control list -- find your orgId and permissions
apple-ads-cli acl

# Authenticated user details (userId, parentOrgId)
apple-ads-cli me

Apps

# Search for iOS apps to promote
apple-ads-cli search-apps "fitness"
apple-ads-cli search-apps "my app name" --return-own-apps --limit 10 --offset 0

# Check if an app is eligible for promotion
apple-ads-cli app-eligibility 123456789

# Get app details by Adam ID
apple-ads-cli app 123456789

search-apps options:

• --return-own-apps -- only return apps owned by the organization
• --limit <n> -- number of results (default 20)
• --offset <n> -- pagination offset (default 0)

Campaigns