Manage Ads Manager from the CLI

The Adapty CLI can manage your Ads Manager account from the terminal, under the adapty asa topic. It covers campaigns, ad groups, keywords, ads, product pages, automation rules, metrics, and competitor research.

Use it for the work that a browser makes slow: giving an AI agent live access to your ad performance, adding several hundred keywords from a file, and running the same setup across several campaigns. For everything else, the dashboard remains faster.

Before you start

Ads Manager commands use the same installation and login as the rest of the CLI. If you have not set that up, follow steps 1 and 2 of the quickstart guide.

Prerequisites

Two further conditions apply to every adapty asa command:

• A connected Apple Ads account: Connect it with adapty asa connect, or in the dashboard as described in Get started with Adapty Ads Manager.
• An active Ads Manager subscription: Without one, every command fails with 402 ads_manager_subscription_required.

One command reports both:

adapty asa whoami

Differences from the rest of the CLI

• There is no --app flag: The scope is the company your token belongs to. --app exists on some list commands as a filter only.
• Writes reach Apple directly: Each command that changes your account prints the request body and asks for confirmation before sending it. There is no staging step.
• Reads are cheap, writes are not: Run list commands and --dry-run freely. Treat everything else as irreversible.

To skip the confirmation prompt in a script, pass --yes. Under --json or in a pipe, a write command refuses instead of waiting for an answer that will never arrive, so --yes is required there.

Find the IDs you need

Every command takes UUIDs, and every UUID comes from a list command. Work down the hierarchy:

adapty asa orgs list
adapty asa campaigns list --campaign-group <campaign-group-id>
adapty asa ad-groups list --campaign <campaign-id>

Scope each read with a filter. Filters narrow the query rather than the printed page, so a scoped read is cheap while an unscoped one pages through the whole account. adapty asa keywords list without --ad-group is the widest read in the topic.

These lists return metadata only. Performance numbers come from asa metrics.

Add keywords in bulk

Adding keywords one at a time is the main reason to leave the dashboard. Put one keyword per line in a text file:

adapty asa keywords add --ad-group <ad-group-id> --from-file keywords.txt --bid 1.20 --match-type EXACT

Keywords are applied as a batch of at most 100 per call. Split larger lists across several calls.

Two kinds of failure are possible, and they behave differently. An invalid ID fails the whole batch before Apple is called, so nothing is applied. Apple can also reject individual keywords — the rest are still added, and each rejection is reported with its reason. Check the summary line rather than the exit code alone.

Start with a handful of keywords and check the result before sending a full file.

Query metrics from agents and scripts

asa metrics reports on any level of the account over a date range. Add --json so an AI agent or a script can consume the result directly:

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric spend --metric roas --json

--metric takes the names that Ads Manager tracks. See Metrics for the full list.

Cohort metrics work differently from the rest. There is no ltv metric, because lifetime value is read at a renewal window rather than on a date. Ask for the window instead:

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --metric roas --by-days 7 --by-days 90 --order-by-day 90

This returns your campaigns ranked by day-90 ROAS. Up to 16 windows fit in one call.

Each row is one entity, already aggregated and sorted on the server. A “top five campaigns by spend” question is therefore one call, not a pass over every page:

adapty asa metrics --entity campaign --date-from 2026-07-01 --date-to 2026-07-31 --order-by spend --page-size 5

Metrics and the search terms list share one analytics budget per company: 5 calls per minute, and at most 2 in any 10 seconds. Ask a narrow question once rather than polling. The reporting period is also capped by how finely you group it — 90 days by day, 180 by week, 365 by month — so widen a report by coarsening --group-by, not by splitting it into more calls.

Check competitor keywords

One command returns the keywords that competing apps bid on, for up to five App Store apps at a time:

adapty asa competitors summary --app-ids 1668337467,6503873027 --json

The period and the countries are fixed on the server — the last full month, across every country — so the command has no flags beyond the app IDs. The first call for a set of apps can take tens of seconds.

Use this to pull competitor keyword data into a report on a schedule. To filter the results, compare countries side by side, or add the keywords you find straight to a campaign, use Market Intelligence in the dashboard instead.

Run automation rules

The CLI does not build automation rules — it stores the JSON you give it. The fastest way to get a valid rule file is to build one rule in the dashboard, then read it back:

adapty asa automations get <automation-id> --json > rule.json

Edit that file and use it as the template for new rules:

adapty asa automations create --file rule.json

When you pass a file to automations update, remove the internal_id field first — the update is rejected if it is present.

Test a rule before letting it change bids:

adapty asa automations run <automation-id> --dry-run

A dry run evaluates the conditions and logs what the rule would do without touching Apple Ads. Runs are queued rather than performed immediately, so the command prints a run ID and the outcome appears in adapty asa automations runs.

Re-run scripts safely

Every write sends an idempotency key. The CLI generates one per invocation and retries once after a network error, so a request that failed in transit is never applied twice.

In a script, pin the key yourself so the whole pipeline can be re-run:

adapty asa campaigns create --org <campaign-group-id> --name "Winter push" --adam-id 123456 --country US --daily-budget 50 --idempotency-key winter-push-2026 --yes

Re-running the same command within 24 hours returns the stored result and prints Already applied earlier instead of creating a second campaign. The same key with a different body fails with 422, which catches an edited script that reuses a key by mistake.

What’s next

• Manage Apple Ads with an AI coding tool — install the ads-manager skill so Claude Code, Copilot CLI, Codex, or Gemini CLI can run these commands for you.
• Ads Manager commands — every command with its arguments, flags, and accepted values.
• Automations — what each rule type does and which actions it can take.
• Metrics — the metric names accepted by --metric and how each one is calculated.