From adc3b78584b3b92e8424e418bffd642677b363d9 Mon Sep 17 00:00:00 2001 From: mlnchk <25712010+mlnchk@users.noreply.github.com> Date: Wed, 30 Sep 2026 15:52:11 +0000 Subject: [PATCH] chore: sync agent docs from adapty-cli --- skills/adapty-cli-setup/SKILL.md | 2 +- skills/apple-ads/references/asa-management.md | 15 ++++++++++++--- skills/apple-ads/references/asa-metrics.md | 2 +- 3 files changed, 14 insertions(+), 5 deletions(-) diff --git a/skills/adapty-cli-setup/SKILL.md b/skills/adapty-cli-setup/SKILL.md index 431d592..7603726 100644 --- a/skills/adapty-cli-setup/SKILL.md +++ b/skills/adapty-cli-setup/SKILL.md @@ -4,7 +4,7 @@ license: MIT description: Use when the Adapty CLI needs installing or authenticating before any Apple Search Ads work — a fresh Cowork or cloud session, "adapty: command not found", AuthRequiredError, an expired auth code, or connecting an Apple Search Ads account. Triggers on "install the Adapty CLI", "set up adapty", "adapty auth login", "connect Apple Search Ads", "not authenticated", or any Apple Ads request made in a session where the CLI is not yet installed. --- - # Adapty CLI setup diff --git a/skills/apple-ads/references/asa-management.md b/skills/apple-ads/references/asa-management.md index 594ce35..b74218a 100644 --- a/skills/apple-ads/references/asa-management.md +++ b/skills/apple-ads/references/asa-management.md @@ -1,4 +1,4 @@ - # Apple Search Ads — Managing Campaigns @@ -31,12 +31,21 @@ Every `list` and `get` command in this file returns metadata only, no metrics. E |---|---|---| | `asa campaigns list` | scope filters only | Metadata only. | | `asa campaigns get ` | positional UUID | Metadata only. | -| `asa campaigns create` | `--org`, `--name`, `--adam-id`, `--country` (repeatable), `--daily-budget`; optional `--status` (`ENABLED`/`PAUSED`, no default), `--budget` (lifetime), `--target-cpa`, `--bidding-strategy`, `--supply-source` (repeatable, default `APPSTORE_SEARCH_RESULTS`), `--billing-event` (`IMPRESSIONS`/`TAPS`, default `TAPS`), `--ad-channel-type` (`DISPLAY`/`SEARCH`, default `SEARCH`), `--invoice-advertiser`, `--invoice-order-number`, `--invoice-contact-name`, `--invoice-contact-email`, `--invoice-billing-email` (all five together, LOC organizations only) | `--org` takes the UUID (`internal_id`) from `asa orgs list`, not that row's numeric `org_id`; `--adam-id` comes from `asa apps list`. `--status` has no default — pass `--status PAUSED` to launch without spending until you enable it. The response carries `serving_status` and `serving_state_reasons`; when the campaign is `NOT_RUNNING` the command prints the reason and the fixing command — see [Max Conversions](#max-conversions-campaigns) and [Line of credit](#line-of-credit-loc-organizations). | -| `asa campaigns update ` | at least one of `--name`, `--status`, `--country`, `--daily-budget`, `--budget`, `--target-cpa`, `--bidding-strategy`, or `--invoice-advertiser`, `--invoice-order-number`, `--invoice-contact-name`, `--invoice-contact-email`, `--invoice-billing-email` together | The `--invoice-*` flags replace the stored Invoicing Options as a whole — pass all five, a partial set exits 2 before the network. | +| `asa campaigns create` | `--org`, `--name`, `--adam-id`, `--country` (repeatable), `--daily-budget`; optional `--status` (`ENABLED`/`PAUSED`, no default), `--target-cpa`, `--bidding-strategy`, `--supply-source` (repeatable, default `APPSTORE_SEARCH_RESULTS`), `--billing-event` (`IMPRESSIONS`/`TAPS`, default `TAPS`), `--ad-channel-type` (`DISPLAY`/`SEARCH`, default `SEARCH`), `--invoice-advertiser`, `--invoice-order-number`, `--invoice-contact-name`, `--invoice-contact-email`, `--invoice-billing-email` (all five together, LOC organizations only) | `--org` takes the UUID (`internal_id`) from `asa orgs list`, not that row's numeric `org_id`; `--adam-id` comes from `asa apps list`. `--status` has no default — pass `--status PAUSED` only when the user asks to launch without spending (see [Budget and serving](#budget-and-serving)). The response carries `serving_status` and `serving_state_reasons`; when the campaign is `NOT_RUNNING` the command prints the reason and the fixing command — see [Max Conversions](#max-conversions-campaigns) and [Line of credit](#line-of-credit-loc-organizations). | +| `asa campaigns update ` | at least one of `--name`, `--status`, `--country`, `--daily-budget`, `--target-cpa`, `--bidding-strategy`, or `--invoice-advertiser`, `--invoice-order-number`, `--invoice-contact-name`, `--invoice-contact-email`, `--invoice-billing-email` together | The `--invoice-*` flags replace the stored Invoicing Options as a whole — pass all five, a partial set exits 2 before the network. | | `asa campaigns bulk-create` | exactly one of `--file` (JSON structure, `-` for stdin) / `--from-file` (Apple Ads template, `.xlsx` or keywords `.csv`); `--org-id` required with `--from-file`; optional `--preview`, `--no-wait`, `--poll-interval` (default `5`), `--timeout` (default `900`) | Creates a whole structure — campaigns → ad groups → keywords/negative keywords/ads — as one queued operation. `--org-id` is the exception to this file's UUID rule: it takes the **numeric** `org_id` from `asa orgs list` (Apple's `campaign_group_id`), not the `internal_id` UUID that `campaigns create --org` takes. `--from-file` converts the template server-side first (its own budget — see [Request budgets](#request-budgets)); with `--preview` the command prints the converted request and creates nothing. By default it polls until the operation finishes (`success`/`partial`/`failed`, per-object failures listed); `--no-wait` prints the `operation_id` and returns — follow up with `bulk-status`. | | `asa campaigns bulk-status ` | positional operation id, printed by `bulk-create` | Progress of one bulk operation: status, applied/failed counts, and the per-object log with each failure's reason. | | `asa campaigns bulk-list` | optional `--status` (`pending`/`running`/`success`/`partial`/`failed`, repeatable), `--app` (UUID), `--created-from`/`--created-to` (YYYY-MM-DD) | This company's bulk operations, newest first — one row per operation with its verdict and timestamps, no per-object detail. Use it to find an `operation_id` you lost or to check what ran recently, then drill in with `bulk-status`. Cheap catalog read. | +### Budget and serving + +- Budget always means `--daily-budget`. Apple does not support lifetime budgets; if the user gives a total for a + period, divide it by the number of days and confirm the daily amount before writing. +- A campaign serves only when the campaign, its ad groups and its keywords are all enabled (`ENABLED`; keywords + `ACTIVE`). Create them `PAUSED` only if the user asks; after setup, list anything still paused and offer to enable + it (`asa campaigns update --status ENABLED`, `asa ad-groups update --status ENABLED`, + `asa keywords update --status ACTIVE`). + ### Max Conversions campaigns A campaign with `--bidding-strategy MAX_CONVERSIONS` is created fine but stays `NOT_RUNNING` with diff --git a/skills/apple-ads/references/asa-metrics.md b/skills/apple-ads/references/asa-metrics.md index 16d702a..fa9b19d 100644 --- a/skills/apple-ads/references/asa-metrics.md +++ b/skills/apple-ads/references/asa-metrics.md @@ -1,4 +1,4 @@ - # Apple Search Ads — Metrics and Analytics