Apple Search Ads Management
Full management of Apple Search Ads campaigns for iOS apps using the ASA CLI tool.
Capabilities
This skill enables you to:
- Set up Apple's recommended 4-campaign structure
- Add keywords with automatic routing (exact → target, broad → discovery, negative → discovery)
- Full negative keyword CRUD (list, add, delete at campaign and ad group level)
- Bulk keyword bid updates across entire campaigns
- Search/find keywords across all ad groups
- Promote winning keywords from Discovery to exact match campaigns
- Generate performance reports (campaign, keyword, ad group, search term, impression share, ad-level)
- Create and manage async custom reports for large date ranges
- View bid recommendations from Apple's keyword insights
- Manage budget orders and monitor campaign budget health
- Search and set geo targeting (countries, regions, cities)
- Manage ad variations, creative sets, and product pages
- View ad rejection reasons
- Access control management (ACLs, user info, app search, eligibility)
- Audit campaign structure against Apple's best practices
- Pause/enable campaigns
- Automated optimization — analyze search terms and batch promote/block keywords
Prerequisites
Running with uv (Recommended)
No installation required. Just use uv run:
cd /path/to/apple-search-ads-cli
uv run asa config setup
uv run asa campaigns list
Alternative: pip install
cd /path/to/apple-search-ads-cli
pip install -e .
asa config setup
Configuration
uv run asa config setup
You'll need from Apple Ads dashboard (https://ads.apple.com/):
- Organization ID
- Client ID, Team ID, Key ID
- Private key file (EC key pair)
To generate keys:
openssl ecparam -genkey -name prime256v1 -noout -out private-key.pem
openssl ec -in private-key.pem -pubout -out public-key.pem
Verify Setup
asa config test
Command Reference
Configuration Commands
| Command | Description |
|---|---|
asa config setup | Interactive credential and app setup |
asa config show | Display current configuration |
asa config test | Test API connection |
Campaign Commands
| Command | Description |
|---|---|
asa campaigns list | List all campaigns |
asa campaigns list --bids | Include ad group default bids |
asa campaigns list --filter "term" | Filter campaigns by name |
asa campaigns list --status RUNNING | Filter by status (RUNNING, PAUSED) |
asa campaigns create <name> | Create a new campaign |
asa campaigns update <ID> | Update campaign name/budget/status |
asa campaigns audit | Check structure vs Apple recommendations |
asa campaigns audit --verbose | Show detailed ad group info |
asa campaigns setup | Create 4-campaign structure |
asa campaigns setup --dry-run | Preview without creating |
asa campaigns pause <ID> | Pause specific campaign |
asa campaigns pause --all | Pause all managed campaigns |
asa campaigns enable <ID> | Enable specific campaign |
asa campaigns enable --all | Enable all managed campaigns |
asa campaigns delete <ID> | Delete specific campaign |
Ad Group Commands
| Command | Description |
|---|---|
asa adgroups list <campaign_id> | List ad groups for a campaign |
asa adgroups create <name> -c <campaign_id> | Create a new ad group |
asa adgroups update <ID> -c <campaign_id> | Update ad group settings |
asa adgroups pause <ID> -c <campaign_id> | Pause an ad group |
asa adgroups enable <ID> -c <campaign_id> | Enable an ad group |
asa adgroups delete <ID> -c <campaign_id> | Delete an ad group |
Keyword Commands
| Command | Description |
|---|---|
asa keywords list | List keywords (interactive selection) |
asa keywords list --campaign <ID> | List keywords for specific campaign |
asa keywords list --negatives | List negative keywords |
asa keywords list --filter "term" | Filter keywords containing text |
asa keywords list --status ACTIVE | Filter by status (ACTIVE, PAUSED) |
asa keywords list --match-type EXACT | Filter by match type (EXACT, BROAD) |
asa keywords add "<kw1>,<kw2>" --type brand | Add brand keywords |
asa keywords add "<kw1>,<kw2>" --type category | Add category keywords |
asa keywords add "<kw1>,<kw2>" --type competitor | Add competitor keywords |
asa keywords add-negatives "<kw1>,<kw2>" --all | Block terms in all campaigns |
asa keywords add-negatives "<kw1>,<kw2>" --all --force | Block terms without confirmation |
asa keywords list-negatives | List all campaign and ad-group level negatives |
asa keywords list-negatives --campaign <ID> | List negatives for specific campaign |
asa keywords delete-negatives <IDS> | Delete negative keywords by comma-separated IDs |
asa keywords find "<query>" | Search targeting keywords across all ad groups |
asa keywords update-bids-bulk --bid <AMOUNT> | Bulk update all keyword bids in a campaign |
asa keywords promote "<kw1>,<kw2>" --target category | Graduate from Discovery |
asa keywords delete | Delete keywords (interactive) |
asa keywords delete --ids "123,456" --force | Delete specific keywords by ID |
asa keywords update-bid --bid 2.50 | Update keyword bid amount |
asa keywords pause | Pause a keyword |
asa keywords pause --all | Pause all active keywords in ad group |
asa keywords enable | Enable a paused keyword |
asa keywords enable --all | Enable all paused keywords in ad group |
asa keywords research | Keyword research (stub — requires external tools) |
Report Commands
| Command | Description |
|---|---|
asa reports summary | Performance summary (last 30 days) |
asa reports summary --days 7 | Custom date range |
asa reports keywords | Keyword performance |
asa reports keywords --sort cpa | Sort by CPA |
asa reports adgroups --all | Ad group performance for all campaigns |
asa reports adgroups --campaign <ID> | Ad group performance for specific campaign |
asa reports impression-share --all | Impression share / Share of Voice report |
asa reports impression-share --min-impressions 50 | Filter by minimum impressions |
asa reports search-terms | All search terms |
asa reports search-terms --winners | Terms to promote (good CPA) |
asa reports search-terms --negatives | Terms to block (spend, no installs) |
asa reports custom --days 90 | Create async custom report |
asa reports custom --days 90 --granularity WEEKLY | Custom report with weekly granularity |
asa reports custom-list | List all custom reports (pending/completed) |
asa reports custom-get <ID> | Get or download a custom report by ID |
asa reports ads | Ad-level performance report |
asa reports bid-recommendations | Show keyword bid recommendations from Apple insights |
Budget Commands
| Command | Description |
|---|---|
asa budget list | List all budget orders |
asa budget get <ID> | Get budget order details |
asa budget status | Campaign budget health overview (color-coded) |
asa budget create | Create a new budget order |
Geo Targeting Commands
| Command | Description |
|---|---|
asa geo search "<query>" | Search for geo locations (countries, regions, cities) |
asa geo show | Show geo targeting for all campaigns |
asa geo set --campaign <ID> --countries US,CA | Set country targeting for a campaign |
Ads & Creatives Commands
| Command | Description |
|---|---|
asa ads list --campaign <ID> | List ad variations |
asa ads create --campaign <ID> --ad-group <ID> | Create an ad variation |
asa ads delete <AD_ID> --campaign <ID> --ad-group <ID> | Delete an ad variation |
asa ads creatives --campaign <ID> --ad-group <ID> | List creative sets |
asa ads product-pages | List product |