apple-search-ads-cli

A small, LLM-friendly CLI for the Apple Search Ads API (v5). JSON in, JSON out, structured errors with hints — built to be driven by humans and language-model agents alike.

Install

npm i -g @krunal202/apple-search-ads-cli   # exposes the `asa` binary

Or from source:

npm install
npm link

Requires Node.js ≥ 18. Single runtime dependency: commander.

Quickstart

# 1. Get API credentials — full walkthrough: CREDENTIALS.md
#    (Apple Search Ads UI → invite an API-role user → upload a public key)
asa login --client-id <id> --team-id <id> --key-id <id> --key-file ./asa-private-key.p8

asa orgs list && asa orgs use <orgId>

asa campaigns list --pretty
asa campaigns create --name "Launch" --budget 1000 --currency USD --adam-id 123456789 --countries US
asa adgroups create --campaign <id> --name "Core" --bid 0.50 --currency USD
asa keywords create --campaign <id> --adgroup <id> --text "my app" --match-type EXACT

asa stats campaigns --start 2026-09-01 --end 2026-09-15 --granularity DAILY --pretty

asa copy campaign <id>
asa paste --name "Launch - Q4"

asa logout

LLM integration

• asa llm prints the complete machine-readable usage guide (also in LLM_GUIDE.md).
• Output is single-line JSON by default (--pretty for humans).
• Errors are structured JSON on stderr with a hint field describing the corrective action; unknown commands include "did you mean" suggestions.
• Every create/update accepts --data '<json>' for fields not covered by flags.

Memory for agents

asa remembers what happened so an LLM starting a fresh session can pick up context:

• Every mutating API call is logged automatically per org (~/.asa/memory/<orgId>/activity.jsonl).
• asa remember "note" [--campaign <id>] stores decisions and rationale.
• asa context [--live] prints notes + recent activity (+ current campaigns) — the recommended first command of any agent session.
• asa memory / asa memory --clear inspects or erases the store.

Layout

bin/asa.js            executable entry
src/cli.js            program wiring, error handling
src/config.js         ~/.asa credential/token/clipboard storage
src/api/auth.js       ES256 client-secret JWT + OAuth token exchange
src/api/client.js     authenticated fetch wrapper (X-AP-Context, error mapping)
src/commands/         login/logout/orgs, campaigns, adgroups, keywords, negatives,
                      apps, stats, copy/paste, llm guide
test/                 node:test unit tests (npm test)

Not yet covered by the CLI: ad creative / custom product page management and budget orders (campaigns are served with the default product page ad).

License

MIT

Sponsors

Maintaining API coverage as Apple evolves the Search Ads API takes ongoing work. If this CLI saves you time, consider sponsoring:

• Buy Me a Coffee
• GitHub Sponsors (button on the repo page once enabled)
• Questions or sponsorship inquiries: @krunaldoshi202 on X

Sponsors can be listed here and in release notes; reach out for logo placement or priority feature requests.