Apple Search Ads

---

name: Apple-Search-Ads description: Manage Apple Search Ads campaigns, ad groups, keywords, and reports via the asa-cli tool. Use when the user asks about Apple Search Ads management, campaign operations, keyword bidding, ASA reports, or ad performance.

---

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, < LT, >= 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

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