ads-manager

name	ads-manager
description	Use when managing Apple Search Ads through the Adapty CLI — reading campaign, ad group, keyword or ad performance, changing bids or budgets, adding or pausing keywords, launching or pausing a campaign, harvesting search terms, or setting up rule-based ad automations.

Apple Search Ads through the Adapty CLI

Reads and automations run --dry-run cost nothing. Every other asa command reaches Apple within seconds and spends real money, and nothing it creates can be deleted or undone.

Open the reference a workflow names before running its commands:

• references/asa-management.md — campaigns, ad groups, ads, keywords, negative keywords, product pages, creatives, automations.
• references/asa-metrics.md — metrics, metrics overview, search-terms list, competitors summary.

The CLI

Resolve $ADAPTY once, before your first asa call, and use it for every command you run. A global adapty is frequently old — the asa topic ships in 0.4.0, and an older install answers every command in this skill with unknown command, which reads like the command does not exist rather than like a stale CLI:

adapty --version                                   # >= 0.4.0 ?  ADAPTY="adapty", done
npm i -g adapty@latest >/dev/null 2>&1 \
  && ADAPTY="adapty" \
  || ADAPTY="npx --yes adapty@latest"              # fallback: prefix not writable

Install once; do not wrap every call in npx. The wrapper costs ~1 s per call against 0.07 s installed, and an optimization pass makes dozens of calls. Where the global prefix is not writable the npx form still works, and there --yes is not optional: without it npx stops to ask permission to install, and a headless run has nobody to answer.

Writing a command out for the user? Expand it to a literal adapty. Their shell has no $ADAPTY. Same split as --yes below — what you run carries the variable, what they run carries the command name.

In zsh, the macOS default, a multi-word $ADAPTY is not split into words, so the command fails with command not found: npx --yes adapty@latest. Run setopt shwordsplit once in the same shell, or write npx --yes adapty@latest out in full. That error is a shell problem, never evidence that the CLI or the command is missing.

Declare an asa command unavailable only after npx --yes adapty@latest lacks it — never from a version number you read somewhere.

Account surface

• $ADAPTY asa whoami — company, how access was granted, Apple connection state. Run it first.
• $ADAPTY asa connect [--no-wait] — prints the Apple authorization link and waits; --no-wait returns immediately.
• $ADAPTY asa orgs list — ASA organizations. Each row carries two identifiers, not interchangeable: internal_id, the UUID --org takes on campaigns create and --campaign-group takes on the lists that accept scope filters, and org_id, Apple's numeric id, which both reject. --org itself exists only on campaigns create; no list accepts it.
• $ADAPTY asa apps list — apps promoted in Apple Search Ads. Each row carries two identifiers, not interchangeable: Apple's numeric adam-id (--adam-id) and the ASA app UUID (--app).
• Those two and automations list take pagination only — no scope filters exist.
• Scope is the token's company. No asa command takes --app to select scope — --app is a list filter only.
• 402 ads_manager_subscription_required — no Ads Manager subscription. 404 — not theirs, or does not exist.
• --json for machine-readable output on reads; a write under --json refuses and exits 2. --page (default 1), --page-size (default 100, max 1000) on every list — prefer one big page to a pagination loop.
• ADAPTY_ASA_API_URL overrides the ASA base URL, independently of ADAPTY_API_URL.

The two templates

Fill every slot. A slot you cannot fill from a read is one you ask about, not one you drop.

$ADAPTY asa <topic> list --<filter-from-that-list-s-matrix-row> <id-from-a-previous-list> [--status <enum>]
$ADAPTY asa <topic> <create|update|add> [<id>] <field flags> --idempotency-key <key>

The scope filter is a required slot, and the matrix is the only place it comes from — read that list's own row in references/asa-management.md, ## Scope filters, and fill the slot from it. A flag you saw on a create command, or on a different list, is not a filter for this one: --org belongs to campaigns create, and the equivalent on the lists that take scope filters at all is --campaign-group. Required on a session's first list as much as its fifth — a filter changes the query the server ranks, while page size only changes how much of the wrong answer you see.

Two entities the user named separately are two lookups. "The best-performing campaign" and "the brand ad group" are not parent and child unless the user said so. Resolve each by its own name (ad-groups list --search <name>), and never scope one lookup with an id produced by resolving the other — that filter asserts a relationship the user did not state, and the write that follows lands somewhere plausible and wrong without erroring. More than one match is where you ask, not pick.

--idempotency-key is a required slot, distinct per write in a chain and per batch within a write. The CLI's auto key covers a network retry inside one invocation, not the person who re-runs your create step after an ambiguous result — new invocation, fresh key, second campaign. That, plus 422 cli_idempotency_key_reuse and 409 cli_idempotency_in_progress: references/asa-management.md, ## Writes and idempotency.

--yes is not in the template, because whether it belongs depends on who runs the command.

• The user runs it — you are writing commands out for them. Omit --yes. At their terminal the CLI prints the exact request body and waits; that prompt is their confirmation, and --yes is the one flag that deletes it. Nothing in your surrounding text puts it back, so no warning, STOP block, or stated assumption substitutes for leaving the flag off.
• You run it — in this session. Ask, get an explicit yes, then append --yes to the command you run.

metrics, metrics overview, search-terms list and competitors summary share 2 concurrent queries per company: 429 cli_analytics_busy is a full pool, 429 cli_rate_limit_exceeded a full window, and 429 cli_cooldown_active the escalating 5m → 30m → 3h lockout. See references/asa-metrics.md, ## The analytics pool.

One question, one call

The server aggregates and the server ranks. Decide the single call that answers the question before running anything; the metrics budget is 5 calls per minute (references/asa-metrics.md).

• Totals: one metrics overview call.
• Best or worst N: one metrics --order-by <metric> --page-size N call, --order asc for worst.
• Trend or period comparison: one call — a per-period series already contains both periods.
• Counting entities: no metrics call at all. Any list with --page-size 1 returns meta.pagination.count.
• metrics and metrics overview take no scope filters at all. You narrow by entity level and window, then match the returned rows against the ids from a scoped list.
• A window too wide for its bucket is cured by coarsening, never by splitting. Caps: 90 days at day grain or with no period grouping, 180 by week, 365 by month and coarser. A year of data is one call at --group-by month (or --period-unit month), not four 90-day calls.

Never sum pages client-side, never call once per period, and never add a comparison the user did not ask for — propose that in the answer instead.

Never

• Never settle a superlative yourself. "Best-performing", "losing", "terrible ROAS" are business definitions, not query results. Name the metric and the window, get the user's yes on that definition, then write.
• Never write without naming the change in chat first — which campaign, which budget, how many keywords.
• Never put more than 15 keywords in one keywords add or negative-keywords add call. The cap is 100; the practice is 15.
• Never loop on a 429. The CLI already waited the exact Retry-After and retried once, so a 429 that reaches you means the budget is genuinely gone. Cut the number of calls, or tell the user when to retry.
• Never guess or probe a metric name. The vocabulary is in references/asa-metrics.md. A wrong name fails listing every valid one, so a typo costs one call — spending a call to see what works is the failure. Cohort metrics rank by their expanded names: --order-by gross_roas, not --order-by roas.
• Never invent an id, adam-id, budget or bid. Read it from the matching list, or ask.
• Never put --yes on a command the user will run. It deletes the preview they would have read. --yes belongs only on a command you run yourself, after an explicit yes.
• Never write a teardown. No delete exists in the asa topic and there is no undo; --status PAUSED is the only stop.

Rationalizations

What the agent told itself	What is actually true
"40 keywords is under the CLI's 100-per-call batch limit, so this is one call, not a loop."	Under the cap is not the same as safe. Nine rejected rows inside a 40-item response is a repair job; inside a 15-item call it is a re-run.
"I'd use ROAS over a trailing window as the default definition of "best-performing," and ask the user to confirm/override it before step 5 — but here is the command that answers it."	Handing over the command does not obtain the sign-off you just said had to come first. If the definition needs confirming, stop at the definition.

Red Flags — STOP

• A list with no scope filter — including the first one, and the one you are "only glancing at"
• A scope filter on orgs list, apps list or automations list
• A filter you did not read off that list's own row in the matrix — a create flag such as --org, or another list's filter, is not one
• --yes on a command you are handing to the user — it deletes the preview they were going to read
• A lookup scoped by an id that came from resolving a different entity the user named separately
• A create in a chain of dependent creates with no --idempotency-key pinned
• More than 15 keywords in one call
• A write whose target you picked by your own definition of "best", "losing" or "terrible"
• --order-by-day with no matching --by-days window in the same call
• You stated a rule, and three commands later are making a silent exception to it

Observed in CLI-side sessions rather than in this skill's own baseline:

• Looping --page 1..4 to build a total, instead of one overview call or one big page
• Spending a call to discover which metric names are valid
• Adding a period comparison the user did not ask for
• Retrying a 429 after a guessed sleep instead of the Retry-After value

All of these mean: stop, read first, ask.

Workflows

1. Orient. whoami → connect if Apple is unlinked → orgs list → apps list. Prerequisite for everything below. → references/asa-management.md, ## Account and discovery.

2. Report performance. Totals and any trend take the first shape; best or worst N takes the second, with --order asc for worst. Dates are required on both — without them the command exits before it reaches Apple. Counting needs no metrics call: any list at --page-size 1 carries meta.pagination.count. --by-days takes max 16 windows per call, and --order-by-day may only name one of those values. → references/asa-metrics.md, ## Cohort windows.

$ADAPTY asa metrics overview --entity <level> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> [--period-unit <bucket>]
$ADAPTY asa metrics --entity <ad|ad-group|campaign|keyword> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> --order-by <metric> --page-size <n>

3. Launch a campaign. Read orgs list → --org and apps list → --adam-id first; then each create consumes an id the previous printed. Neither the order nor any key is optional. Mint <run> once per launch, so a second launch cannot collide. Create the campaign PAUSED, verify the structure, then enable it with workflow 6 — nothing spends until you do. Set --match-type yourself: it defaults to BROAD, which is the widest, most expensive targeting. → references/asa-management.md, ## Writes and idempotency.

$ADAPTY asa campaigns create --org <id> --adam-id <adam-id> --name <name> --country <country-code> --daily-budget <amount> --status PAUSED --idempotency-key <run>-camp
$ADAPTY asa ad-groups create --campaign <id> --name <name> --default-bid <amount> --idempotency-key <run>-ag
$ADAPTY asa creatives list --app <app-uuid>   # → --creative-id; no creatives create exists
$ADAPTY asa ads create --ad-group <id> --creative-id <id> --name <name> --idempotency-key <run>-ad
$ADAPTY asa keywords add --ad-group <id> --text <keyword> --match-type <EXACT|BROAD> --idempotency-key <run>-kw-1   # ≤15 per call, fresh key per batch

4. Harvest keywords. Read search-terms list --ad-group <id> --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> (dates default to today, so pass them), then promote converting terms with keywords add --ad-group <id> and block wasteful ones with negative-keywords add --ad-group <id> — 15 per call, own key per call. → references/asa-metrics.md, ## The analytics pool, and references/asa-management.md.

5. Optimization pass. Read metrics --entity keyword --date-from <YYYY-MM-DD> --date-to <YYYY-MM-DD> --by-days 7 --by-days 90 --order-by gross_roas --order-by-day 90 — --order asc asks that same call for the losers instead of the winners — and keywords list --ad-group <id> --status ACTIVE for ids. Get the user's cutoff before any write. Then keywords update <ids> --bid <amount> on winners, keywords update <ids> --status PAUSED on losers, campaigns update <id> --daily-budget <n> to shift spend — each with its own --idempotency-key. Confirm the budget separately from the bids; separate decisions. → references/asa-metrics.md, ## Cohort windows, and references/asa-management.md.

6. Pause or resume. Campaigns, ad groups, ads: update <id> --status ENABLED|PAUSED --idempotency-key <key>. Keywords: update <id> [<id>…] --status ACTIVE|PAUSED --idempotency-key <key>. The keyword enum differs from every other entity's, and there is no DISABLED anywhere in the surface. Ids come from a scoped list first. → references/asa-management.md, ## Status.

7. Custom product page → ad. product-pages sync [--adam-id <adam-id>] --idempotency-key <key> — a write, queued rather than awaited. Then product-pages list --app <app-uuid> → creatives list --app <app-uuid> → ads create --ad-group <id> --creative-id <id> --name <name> --idempotency-key <key>. → references/asa-management.md.

8. Diagnose a dead ad. ads get <id>, read serving_state_reasons; if that does not explain it, walk up to ad-groups get <id> status, then campaigns get <id> status and daily budget. All reads. → references/asa-management.md.

9. Rule automations. automations create --file rule.json --idempotency-key <key> → automations run <id> --dry-run → automations runs <id> to read what it would have done → automations update <id> --start, only after the user has seen that outcome. Dry-run every rule touching a bid or a budget. → references/asa-management.md.

10. Competitor check. competitors summary --app-ids <adam-id>,<adam-id> — 1–5 Apple App Store IDs. Last full month, every country; no period or country flags exist. Read-only, shares the analytics pool, slow on a cold cache. → references/asa-metrics.md.

Anything not covered here

1. This file and its two references are the source of truth for the asa surface.
2. $ADAPTY asa <topic> <command> --help — exact flag syntax for the installed version.
3. The CLI repo, https://github.com/adaptyteam/adapty-cli (default branch): README.md, then skills/adapty-cli/references/cli-commands.md — both can lag the installed CLI — then src/commands/asa/**, where a command's own static flags declaration outranks any table and settles a disagreement between prose and commands.

Do not guess a flag, a command, or a URL path. If none of the three confirms it, say so.