apple-search-ads

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