Skill: trebuhs/apple-search-ads-skill (version 1.0.0)

--- 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 ```bash 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 ```bash asa-cli campaigns list [--org-id <orgid>] [--limit N] [--offset N] asa-cli campaigns get <id> [--org-id <orgid>] asa-cli campaigns find [--org-id <orgid>] [--filter "status=ENABLED"] [--sort "name:asc"] [--limit N] [--all] asa-cli campaigns create [--org-id <orgid>] --name "..." --budget 1000 --daily-budget 50 --countries US,GB --app-id 123456 asa-cli campaigns update <id> [--org-id <orgid>] [--name ...] [--budget ...] [--daily-budget ...] [--status ENABLED|PAUSED] asa-cli campaigns delete <id> [--org-id <orgid>] ``` ### Ad Groups (require --campaign-id) ```bash asa-cli adgroups list --campaign-id <id> [--org-id <orgid>] asa-cli adgroups get <id> --campaign-id <id> [--org-id <orgid>] asa-cli adgroups find --campaign-id <id> [--org-id <orgid>] [--filter "status=ENABLED"] asa-cli adgroups create --campaign-id <id> [--org-id <orgid>] --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 <id> --campaign-id <id> [--org-id <orgid>] [--name ...] [--default-bid ...] [--status ...] asa-cli adgroups delete <id> --campaign-id <id> [--org-id <orgid>] ``` ### Keywords (require --campaign-id --adgroup-id) ```bash asa-cli keywords list --campaign-id <id> --adgroup-id <id> [--org-id <orgid>] asa-cli keywords get <kwid> --campaign-id <id> --adgroup-id <id> [--org-id <orgid>] asa-cli keywords find --campaign-id <id> --adgroup-id <id> [--org-id <orgid>] [--filter "text~brand"] asa-cli keywords create --campaign-id <id> --adgroup-id <id> [--org-id <orgid>] --text "keyword" [--text "another"] --match-type BROAD|EXACT [--bid 1.50] asa-cli keywords update --campaign-id <id> --adgroup-id <id> [--org-id <orgid>] --id <kwid> [--status ACTIVE|PAUSED] [--bid 2.00] asa-cli keywords delete <kwid,kwid2> --campaign-id <id> --adgroup-id <id> [--org-id <orgid>] ``` ### Negative Keywords ```bash # Campaign-level asa-cli negative-keywords campaign-list --campaign-id <id> [--org-id <orgid>] asa-cli negative-keywords campaign-find --campaign-id <id> [--org-id <orgid>] [--filter "text~free"] asa-cli negative-keywords campaign-create --campaign-id <id> [--org-id <orgid>] --text "term" [--text "another"] --match-type EXACT|BROAD asa-cli negative-keywords campaign-delete <kwid,...> --campaign-id <id> [--org-id <orgid>] # Ad group-level asa-cli negative-keywords adgroup-list --campaign-id <id> --adgroup-id <id> [--org-id <orgid>] asa-cli negative-keywords adgroup-find --campaign-id <id> --adgroup-id <id> [--org-id <orgid>] [--filter "text~competitor"] asa-cli negative-keywords adgroup-create --campaign-id <id> --adgroup-id <id> [--org-id <orgid>] --text "term" [--text "another"] --match-type EXACT|BROAD asa-cli negative-keywords adgroup-delete <kwid,...> --campaign-id <id> --adgroup-id <id> [--org-id <orgid>] ``` ### Reports ```bash asa-cli reports campaigns [--org-id <orgid>] --start-date 2024-01-01 --end-date 2024-01-31 [--granularity DAILY|WEEKLY|MONTHLY] [--group-by countryOrRegion,deviceClass] asa-cli reports adgroups --campaign-id <id> [--org-id <orgid>] --start-date ... --end-date ... asa-cli reports keywords --campaign-id <id> [--org-id <orgid>] --start-date ... --end-date ... asa-cli reports search-terms --campaign-id <id> [--org-id <orgid>] --start-date ... --end-date ... ``` ### Utilities ```bash 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


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: suspicious | SkillSpector: clean (LOW)