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...

README (SKILL.md)

Apple Search Ads CLI

Name: Apple Search Ads
Author: trebuhs

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 \x3Corgid>] [--limit N] [--offset N]
asa-cli campaigns get \x3Cid> [--org-id \x3Corgid>]
asa-cli campaigns find [--org-id \x3Corgid>] [--filter "status=ENABLED"] [--sort "name:asc"] [--limit N] [--all]
asa-cli campaigns create [--org-id \x3Corgid>] --name "..." --budget 1000 --daily-budget 50 --countries US,GB --app-id 123456
asa-cli campaigns update \x3Cid> [--org-id \x3Corgid>] [--name ...] [--budget ...] [--daily-budget ...] [--status ENABLED|PAUSED]
asa-cli campaigns delete \x3Cid> [--org-id \x3Corgid>]

Ad Groups (require --campaign-id)

asa-cli adgroups list --campaign-id \x3Cid> [--org-id \x3Corgid>]
asa-cli adgroups get \x3Cid> --campaign-id \x3Cid> [--org-id \x3Corgid>]
asa-cli adgroups find --campaign-id \x3Cid> [--org-id \x3Corgid>] [--filter "status=ENABLED"]
asa-cli adgroups create --campaign-id \x3Cid> [--org-id \x3Corgid>] --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 \x3Cid> --campaign-id \x3Cid> [--org-id \x3Corgid>] [--name ...] [--default-bid ...] [--status ...]
asa-cli adgroups delete \x3Cid> --campaign-id \x3Cid> [--org-id \x3Corgid>]

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

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

Negative Keywords

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

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

Reports

asa-cli reports campaigns [--org-id \x3Corgid>] --start-date 2024-01-01 --end-date 2024-01-31 [--granularity DAILY|WEEKLY|MONTHLY] [--group-by countryOrRegion,deviceClass]
asa-cli reports adgroups --campaign-id \x3Cid> [--org-id \x3Corgid>] --start-date ... --end-date ...
asa-cli reports keywords --campaign-id \x3Cid> [--org-id \x3Corgid>] --start-date ... --end-date ...
asa-cli reports search-terms --campaign-id \x3Cid> [--org-id \x3Corgid>] --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, \x3C LT, >= GTE, \x3C= 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

Usage Guidance

This skill looks like a straightforward guide for using the asa-cli tool — it is coherent with its purpose. Before installing or using it: (1) Ensure you have asa-cli from a trusted source (the skill does not install it for you). (2) Be aware the commands will read/write ~/.asa-cli/config.yaml and token_cache.json and may read a local private key file you point to; avoid providing private keys you don't trust. (3) The skill metadata omitted declaring required binaries and optional env vars (ASA_CLIENT_ID, ASA_TEAM_ID, ASA_KEY_ID, ASA_PRIVATE_KEY_PATH), so provide only the minimal credentials/scopes needed (or use ephemeral credentials). (4) If you want to limit blast radius, run these commands in an isolated environment or review ~/.asa-cli/ contents after use. (5) If you need higher assurance, ask the publisher for the asa-cli binary source and a manifest so you can verify it before running.

Capability Analysis

Type: OpenClaw Skill Name: apple-search-ads-skill Version: 1.0.0 The skill is classified as suspicious due to its reliance on executing external shell commands (`asa-cli`) and handling sensitive credentials, specifically the `--private-key-path` argument in the `asa-cli configure` command, as detailed in `SKILL.md`. While these capabilities are necessary for the stated purpose of managing Apple Search Ads, they represent high-risk operations. The direct execution of external commands and interaction with file paths for private keys could be exploited through vulnerabilities in the agent's input sanitization or the `asa-cli` tool itself, even though the skill itself does not explicitly instruct malicious behavior.

Capability Assessment

ℹ Purpose & Capability

The SKILL.md clearly targets Apple Search Ads and documents asa-cli commands for campaigns, ad groups, keywords, and reports — that matches the skill name/description. However, the metadata declares no required binaries or credentials while the instructions assume the presence of the asa-cli binary and Apple Search Ads credentials (client-id, team-id, key-id, private key path or env vars). This is a minor inconsistency in metadata vs runtime expectations, not an indication of hidden behavior.

✓ Instruction Scope

The runtime instructions remain focused on ASA management and related utilities (jq, date). They do reference reading/writing the ASA CLI config and token cache in ~/.asa-cli/ and using a local private key path; these filesystem actions are expected for a CLI-based integration and are within the stated scope.

✓ Install Mechanism

This is an instruction-only skill with no install spec and no code files, so there is nothing being downloaded or written by the skill itself. The only install expectation is that the asas-cli binary (asa-cli) is present on PATH — the metadata should have declared that but did not.

ℹ Credentials

The SKILL.md documents environment variable overrides (ASA_CLIENT_ID, ASA_TEAM_ID, ASA_KEY_ID, ASA_ORG_ID, ASA_PRIVATE_KEY_PATH) and describes use of a private key file and token cache. The metadata lists no required env vars or primary credential. The credentials referenced are appropriate for Apple Search Ads usage, but the metadata omission is an inconsistency the user should be aware of.

✓ Persistence & Privilege

The skill does not request always:true and does not modify other skills. It will read/write its own CLI config under ~/.asa-cli/, which is normal for a CLI integration and within scope.

Version History

v1.0.0

Initial release of Apple Search Ads management skill. - Provides full command reference for managing Apple Search Ads campaigns, ad groups, keywords, and reports via `asa-cli`. - Includes guidance for authentication, multi-org management, filtering, pagination, and output formatting. - Documents relevant global flags, config options, and environment variable overrides. - Lists recommended best practices for command usage, reporting, and troubleshooting common scenarios.

Metadata

Slug apple-search-ads-skill

Version 1.0.0

License —

All-time Installs 0

Active Installs 0

Total Versions 1

Frequently Asked Questions

What is Apple Search Ads?

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... It is an AI Agent Skill for Claude Code / OpenClaw, with 785 downloads so far.

How do I install Apple Search Ads?

Run "/install apple-search-ads-skill" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is Apple Search Ads free?

Yes, Apple Search Ads is completely free (open-source). You can download, install and use it at no cost.

Which platforms does Apple Search Ads support?

Apple Search Ads is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created Apple Search Ads?

It is built and maintained by TrebuhS (@trebuhs); the current version is v1.0.0.

More Skills

Apple Search Ads