Apple Search Ads

Apple Search Ads CLI

Use asa-cli to interact with the Apple Search Ads Campaign Management API v5. Always use -o json when you need to parse results programmatically.

Organizations

Run asa-cli whoami to list available orgs. For multi-org accounts, pass --org-id with every command (except whoami). Single-org accounts auto-detect the org.

Commands

Auth & Config

asa-cli whoami                          # List all orgs (no --org-id needed)
asa-cli configure --client-id "..." --team-id "..." --key-id "..." --private-key-path "..."
asa-cli configure                       # Interactive mode

Campaigns

asa-cli campaigns list [--org-id ] [--limit N] [--offset N]
asa-cli campaigns get  [--org-id ]
asa-cli campaigns find [--org-id ] [--filter "status=ENABLED"] [--sort "name:asc"] [--limit N] [--all]
asa-cli campaigns create [--org-id ] --name "..." --budget 1000 --daily-budget 50 --countries US,GB --app-id 123456
asa-cli campaigns update  [--org-id ] [--name ...] [--budget ...] [--daily-budget ...] [--status ENABLED|PAUSED]
asa-cli campaigns delete  [--org-id ]

Ad Groups (require --campaign-id)

asa-cli adgroups list --campaign-id  [--org-id ]
asa-cli adgroups get  --campaign-id  [--org-id ]
asa-cli adgroups find --campaign-id  [--org-id ] [--filter "status=ENABLED"]
asa-cli adgroups create --campaign-id  [--org-id ] --name "..." --default-bid 1.50 --start-time "2026-01-01T00:00:00.000" [--cpa-goal 5.00] [--auto-keywords true|false]
asa-cli adgroups update  --campaign-id  [--org-id ] [--name ...] [--default-bid ...] [--status ...]
asa-cli adgroups delete  --campaign-id  [--org-id ]

Keywords (require --campaign-id --adgroup-id)

asa-cli keywords list --campaign-id  --adgroup-id  [--org-id ]
asa-cli keywords get  --campaign-id  --adgroup-id  [--org-id ]
asa-cli keywords find --campaign-id  --adgroup-id  [--org-id ] [--filter "text~brand"]
asa-cli keywords create --campaign-id  --adgroup-id  [--org-id ] --text "keyword" [--text "another"] --match-type BROAD|EXACT [--bid 1.50]
asa-cli keywords update --campaign-id  --adgroup-id  [--org-id ] --id  [--status ACTIVE|PAUSED] [--bid 2.00]
asa-cli keywords delete  --campaign-id  --adgroup-id  [--org-id ]

Negative Keywords

# Campaign-level
asa-cli negative-keywords campaign-list --campaign-id  [--org-id ]
asa-cli negative-keywords campaign-find --campaign-id  [--org-id ] [--filter "text~free"]
asa-cli negative-keywords campaign-create --campaign-id  [--org-id ] --text "term" [--text "another"] --match-type EXACT|BROAD
asa-cli negative-keywords campaign-delete  --campaign-id  [--org-id ]

# Ad group-level
asa-cli negative-keywords adgroup-list --campaign-id  --adgroup-id  [--org-id ]
asa-cli negative-keywords adgroup-find --campaign-id  --adgroup-id  [--org-id ] [--filter "text~competitor"]
asa-cli negative-keywords adgroup-create --campaign-id  --adgroup-id  [--org-id ] --text "term" [--text "another"] --match-type EXACT|BROAD
asa-cli negative-keywords adgroup-delete  --campaign-id  --adgroup-id  [--org-id ]

Reports

asa-cli reports campaigns [--org-id ] --start-date 2024-01-01 --end-date 2024-01-31 [--granularity DAILY|WEEKLY|MONTHLY] [--group-by countryOrRegion,deviceClass]
asa-cli reports adgroups --campaign-id  [--org-id ] --start-date ... --end-date ...
asa-cli reports keywords --campaign-id  [--org-id ] --start-date ... --end-date ...
asa-cli reports search-terms --campaign-id  [--org-id ] --start-date ... --end-date ...

Utilities

asa-cli apps search --query "MyApp" [--owned]
asa-cli geo search --query "US" [--entity ...] [--country-code ...]

Filter Syntax

Operators for --filter: = EQUALS, ~ CONTAINS, @ IN (comma-sep), > GT, = GTE, <= LTE, !~ NOT_CONTAINS.

Example: --filter "status=ENABLED" --filter "name~Brand"

Global Flags

| Flag | Short | Description | |------|-------|-------------| | --output | -o | json or table (default: table) | | --org-id | | Organization ID — required for multi-org accounts, auto-detected for single-org | | --profile | -p | Named config profile | | --verbose | -v | Show HTTP request/response details | | --no-color | | Disable colored output |

Config

• Config stored at ~/.asa-cli/config.yaml, token cache at ~/.asa-cli/token_cache.json
• Profiles: asa-cli configure -p production --client-id "..." ..., then asa-cli campaigns list -p production
• Env var overrides: ASA_CLIENT_ID, ASA_TEAM_ID, ASA_KEY_ID, ASA_ORG_ID, ASA_PRIVATE_KEY_PATH

Guidelines

• Always use -o json and pipe through jq when extracting specific fields
• For multi-org accounts, always include --org-id — run asa-cli whoami -o json to discover org IDs
• Fetch campaign/adgroup IDs first before operating on child resources
• Use --all on find commands to auto-paginate large result sets
• Reports require --start-date and --end-date in YYYY-MM-DD format
• Currency is auto-detected from the org — no need to specify it manually
• Ad group create requires --start-time (ISO 8601 format, e.g. "$(date -u +%Y-%m-%dT%H:%M:%S.000)" for now)
• --auto-keywords defaults to false (search match OFF). Only enable explicitly when creating discovery ad groups
• keywords find may return 404 on paused/deleted campaigns — use keywords list as a fallback
• Default pagination limit is 20. Use --limit 50 (or higher) when expecting more results (e.g. negative keywords)
• Report metrics use v5 field names: totalInstalls, tapInstalls, viewInstalls, totalNewDownloads, totalRedownloads, totalInstallRate, tapInstallRate, totalAvgCPI, tapInstallCPI, avgCPM — not the old v4 names
• Use --grand-totals on campaign reports to get aggregated totals across all campaigns

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TrebuhS
• Source: TrebuhS/Apple-Search-Ads-Skill
• License: MIT

Install and usage instructions live in the source repository linked above.