asc-apple-ads

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha c079831542f6 · 21 Oct 2026Report an issue or request a re-scan

• Publisherrorkai GitHub organizationOwner of the repository this skill is read from
• Source folderrorkai/app-store-connect-cli-skills/skills/asc-apple-adsThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdictc079831542f6A new audit runs when the source changes
• Repository statusNot archivedLast push 1 day ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use when managing Apple Ads with asc, including OAuth profiles, ad-account discovery, Platform API v1 campaigns and targeting, reports, assets, recommendations, guarded mutations, raw requests, and Campaign Management…

---
name: asc-apple-ads
description: Use when managing Apple Ads with asc, including OAuth profiles, ad-account discovery, Platform API v1 campaigns and targeting, reports, assets, recommendations, guarded mutations, raw requests, and Campaign Management API v5 migration.
---

# asc Apple Ads

Run Apple Ads work through `asc ads`. Apple Ads credentials are separate from App Store Connect credentials; `asc auth login` does not configure Ads.

## Pick the API first

- Direct `asc ads <resource> ...` commands use Apple Ads Platform API v1 and an ad account ID.
- Deprecated Campaign Management API v5 commands live under `asc ads v5 ...` and use an organization ID. Apple retires v5 on January 26, 2027.
- Never substitute an org ID for an ad account ID. The CLI keeps them separate.
- Run the exact leaf command with `--help` before building a request file. Platform v1 payloads and response envelopes differ from v5; the CLI does not translate them.
- For non-interactive pipelines, pass `--file -` to read a JSON request body from stdin; the CLI rejects it when stdin is a terminal.
- Resource, report, upload, and raw commands emit lossless JSON. Use `jq` for projections instead of asking for table or markdown output.

## Authenticate and pin the account

Store both contexts when a profile must support v1 and legacy v5:

```bash
asc ads auth login \
  --name "Marketing" \
  --client-id "$ASC_ADS_CLIENT_ID" \
  --team-id "$ASC_ADS_TEAM_ID" \
  --key-id "$ASC_ADS_KEY_ID" \
  --private-key "$ASC_ADS_PRIVATE_KEY_PATH" \
  --ad-account "987654" \
  --org "123456" \
  --network
```

For CI, set Ads-specific variables and bypass the host keychain:

```bash
export ASC_ADS_CLIENT_ID="SEARCHADS_CLIENT_ID"
export ASC_ADS_TEAM_ID="SEARCHADS_TEAM_ID"
export ASC_ADS_KEY_ID="KEY_ID"
export ASC_ADS_PRIVATE_KEY_PATH="$HOME/.asc/apple-ads-private-key.pem"
export ASC_ADS_AD_ACCOUNT_ID="987654"
export ASC_ADS_BYPASS_KEYCHAIN=1
```

`ASC_ADS_PRIVATE_KEY` and `ASC_ADS_PRIVATE_KEY_B64` also work. If another trusted process minted a short-lived token, set `ASC_ADS_ACCESS_TOKEN`; scoped v1 calls still need an ad account ID.

Check auth without printing a token:

```bash
asc ads auth status --validate --output json
asc ads auth discover --ads-profile "Marketing" --output json
asc ads auth doctor --output json
```

Discovery calls Platform v1 `GET /v1/me` and `GET /v1/acls`. Compare each ACL's ad-account ID, name, organization ID, and roles; never select the first result automatically. Print the chosen account before any mutation, then pass both `--ads-profile "Marketing"` and `--ad-account "987654"` when more than one profile or account is available.

For named profiles, the profile's `ad_account_id` and `org_id` stand alone; they do not inherit context from another profile or root config. V1 context precedence is `--ad-account`, `ASC_ADS_AD_ACCOUNT_ID`, the selected profile, then profile-less root config. Legacy v5 uses the matching `--org` and `ASC_ADS_ORG_ID` chain.

## Start read-only

Identity and ACL calls need no ad account context:

```bash
asc ads me view --ads-profile "Marketing" --output json
asc ads acls list --ads-profile "Marketing" --output json
asc ads orgs view --ads-profile "Marketing" --org-id "123456" --output json
```

Then prove the selected account with a small app search:

```bash
asc ads apps search \
  --ads-profile "Marketing" \
  --ad-account "987654" \
  --query "Example" \
  --limit 1 \
  --output json
```

App search requires at least one of `--query`, `--cpids`, or `--return-owned-apps`. Storefronts use comma-separated ISO alpha-2 codes. Add `--paginate` only when every search result is needed.

Use each resource's `find` command for inventory. Most v1 queries put filters, sorting, and pagination in a JSON object. A subordinate-resource filter looks like this:

```json
{
  "filters": [
    {"field": "campaignId", "operator": "EQUALS", "value": ["campaign-id"]}
  ],
  "pagination": {"offset": 0, "pageSize": 100, "fetchTotalCount": true}
}
```

```bash
asc ads campaigns find --ads-profile "Marketing" --ad-account "987654" --output json
asc ads ad-groups find --ads-profile "Marketing" --ad-account "987654" --file query.json --output json
asc ads ads find --ads-profile "Marketing" --ad-account "987654" --file query.json --output json
```

Omitting `--file` from `campaigns find` requests the default first page. To control or exhaust the result set, use `pagination.offset`, `pageSize`, and `fetchTotalCount` in a query file, read the response pagination, and advance the offset until complete. This command has no `--paginate` flag. Platform filters use the singular `value`; do not copy v5 `Selector` fields such as `conditions` or plural `values`, which current `asc` rejects before auth.

The direct v1 tree also covers ad accounts and advertiser resources; app eligibility, locales, product pages, and rejection reasons; brands, business categories, locations, location groups, creatives, and assets; geographic targeting and shared budgets; reports for apps and brands; insights, suggestions, recommendations, and change history. Discover the exact leaf instead of falling back to raw HTTP:

```bash
asc ads change-history --help
asc ads suggestions --help
asc ads rejection-reasons --help
asc ads reports brands --help
```

Keyword queries need a selector file. Targeting keywords require an `id`, `adGroupId`, or `campaignId` filter. Negative keywords require `id` or `adGroupId`; campaign-level negative keywords combine `campaignId` with an `adGroupId` filter whose operator is `IS_NULL`.

```bash
asc ads targeting-keywords find --ads-profile "Marketing" --ad-account "987654" --file keyword-query.json --output json
asc ads negative-keywords find --ads-profile "Marketing" --ad-account "987654" --file negative-keyword-query.json --output json
```

## Reports and optimization

V1 reports require an endpoint-specific body. Dates live under `timeRange`, page controls use `offset` and `pageSize`, and campaign or ad-g

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/rorkai/app-store-connect-cli-skills
git -C app-store-connect-cli-skills checkout c079831542f6

Works in

1. 2026-10-21
   ✓SAFE B 89 / 100

   first audit · source c079831542f6

Questions about asc-apple-ads

• github.com/rorkai/app-store-connect-cli-skills/tree/main/skills/ — the audited source at commit c079831542f6 and every finding aboveObserved · 21 Oct 2026

Spotted something wrong? Report a correction · Methodology