rorkai/app-store-connect-cli-skills

# ASC ad hoc distribution

Use the experimental `asc distribute` workflow to turn an existing iOS archive
into a private, verified install link for registered devices. Use TestFlight or
the App Store release skills instead when the build should go through Apple-hosted
distribution.

Confirm the installed contract before acting:

```bash
asc distribute --help
asc distribute plan --help
asc distribute apply --help
asc distribute resume --help

# asc analytics reports

Collect a complete set of analytics report segments and verify the compressed
files before handing them to a separate analysis workflow. Do not interpret,
aggregate, or present the report contents as part of this skill.

## Guardrails

- Treat report inventories, signed URLs, downloaded segments, and identifiers as
  confidential business data.
- Prefer an existing request. Creating a request changes App Store Connect state
  and requires an Admin-authorized profile; obtain explicit user approval before
  running `asc analytics request`.
- Never delete or replace a request as part of collection.

# asc app create (UI automation)

Use this skill to create a new App Store Connect app by driving the web UI.
This is opt-in, local-only automation that requires the user to be signed in.

## Preconditions
- A browser automation tool is available (Playwright, Cursor browser MCP, or equivalent).
- User is signed in to App Store Connect (or can complete login + 2FA).
- The **bundle ID must already be registered** in the Apple Developer portal.
- Required inputs are known:
  - app name (max 30 characters)
  - bundle ID (must exist and be unused by another app)
  - SKU
  - platform (iOS, macOS, tvOS, visionOS)

# 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

# asc ASO audit

Run a two-phase ASO audit: offline checks against local metadata files, then keyword gap analysis via Astro MCP.
When available, include Apple-generated app tags as a discoverability signal.

## Preconditions

- Metadata pulled locally into canonical files via `asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata"`.
- If metadata came from `asc migrate export` or `asc localizations download`, normalize it into the canonical `./metadata` layout before running this skill.
- For Astro gap analysis: app tracked in Astro MCP (optional — offline checks run without it).
- For Apple-generated discoverability tags: `asc app-tags list --app "APP_ID" --output json` works when the API returns tags for the app.

## Before You Start

# asc build lifecycle

Use this skill to manage build state, processing, and retention.

## Find the right build
- Latest build:
  - `asc builds info --app "APP_ID" --latest --version "1.2.3" --platform IOS`
- Next safe build number:
  - `asc builds next-build-number --app "APP_ID" --version "1.2.3" --platform IOS`
  - The command scans the full processed-build history and in-flight uploads, then returns one greater than the highest positive numeric build number. Blank or non-numeric processed build numbers are skipped with a warning; if no usable number remains, it falls back to `--initial-build-number`.
- Recent builds:
  - `asc builds list --app "APP_ID" --sort -uploadedDate --limit 10`

## Inspect processing state

# asc cli usage

Use this skill when you need to run or design `asc` commands for App Store Connect.

## Command discovery
- Always use `--help` to discover commands and flags.
  - `asc --help`
  - `asc builds --help`
  - `asc builds list --help`
- Use `asc search` for local, deterministic command discovery when you know the workflow but not the command path.
  - `asc search "submit app for review"`
  - `asc search --output table "upload build"`
- Use `asc schema` to inspect bundled App Store Connect endpoint schemas and request/query fields before designing API-facing commands.
  - `asc schema --pretty "GET /v1/apps"`

# asc crash triage

Use this skill to fetch, analyze, and summarize TestFlight crash reports, beta feedback, and performance diagnostics.

## Workflow

1. Resolve the app ID if not provided (use `asc apps list`).
2. Fetch data with the appropriate command, using `--output json` for responses that will be parsed. For `performance download`, `--output` is the destination file path.
3. Parse JSON output and present a human-readable summary.

## TestFlight crash reports

List recent crashes (newest first):

# asc id resolver

Use this skill to map names to IDs needed by other commands.

## App ID
- By bundle ID or name:
  - `asc apps list --bundle-id "com.example.app"`
  - `asc apps list --name "My App"`
- Fetch everything:
  - `asc apps list --paginate`
- Set default:
  - `ASC_APP_ID=...`

## Build ID

# asc in-app events

Use `asc app-events` for the requested stages only. A localization, media upload,
or diagnostic request does not authorize creating or submitting another event.
Preserve the resolved app, event, platform, locales, and existing authorization.

## Inspect the target

Check `asc app-events --help` and the relevant subcommand help before execution.
Resolve the app ID and auth profile; inspect an existing event before changing it:

```bash
asc app-events list --app "APP_ID" --paginate --output json
asc app-events view --event-id "EVENT_ID" --output json

# asc localize metadata

Use this skill to pull English (or any source locale) App Store metadata, translate it with LLM, and push translations back to App Store Connect — all automated.

## Command discovery and output conventions

- Always confirm flags with `--help` for the exact `asc` version:
  - `asc localizations --help`
  - `asc localizations download --help`
  - `asc localizations upload --help`
  - `asc apps info edit --help`
- Prefer explicit long flags (`--app`, `--version`, `--version-id`, `--type`, `--app-info`).
- Output defaults are TTY-aware: table in interactive terminals and JSON in CI or other non-interactive contexts. Use explicit `--output` when the format matters.
- Prefer deterministic ID-based operations. Do not "pick the first row" via `head -1` unless the user explicitly agrees.

# asc metadata sync

Use this skill to keep App Store metadata in sync with App Store Connect. Prefer the canonical `asc metadata` workflow for app-info and version localization fields. Use the lower-level `asc localizations` and `asc migrate` commands only when the user specifically needs `.strings` files or legacy fastlane-format metadata.

## Current canonical workflow

### 1. Pull canonical metadata

```bash
asc metadata pull --app "APP_ID" --version "1.2.3" --platform IOS --dir "./metadata"
```

If the app has multiple app-info records, resolve the app-info ID first and pass it explicitly:

# macOS Notarization

Use this skill when you need to notarize a macOS app for distribution outside the App Store.

## Preconditions
- Xcode installed and command line tools configured.
- Auth is configured (`asc auth login` or `ASC_*` env vars).
- A Developer ID Application certificate in the local keychain.
- The app's Xcode project builds for macOS.

## Preflight: Verify Signing Identity

Before archiving, confirm a valid Developer ID Application identity exists:

# PPP pricing (per-territory pricing)

Use this skill to create or update localized pricing across territories based on purchasing power parity (PPP) or your own regional pricing strategy.

Prefer the current high-level flows:
- `asc subscriptions setup` and `asc iap setup` for parent creation and pricing,
  followed by version-scoped metadata commands
- `asc subscriptions pricing ...` for subscription pricing changes
- `asc iap pricing summary` and `asc iap pricing schedules ...` for IAP pricing changes

Prefer native `asc` commands. Use `asc api` only when no native command covers
the task; the `--resolved` reads below already return territory, currency,
customer price, proceeds, and price point ID for every territory.

# App Store release orchestration

Use this skill to carry a release from an approved plan to App Store review. Keep Game Center item preparation here; keep other blocker diagnosis and review recovery in `asc-submission-health`.

## Ownership boundary

This skill owns:

- staging metadata and attaching a build;
- publishing an IPA or building locally;
- submitting a prepared version;
- assembling a multi-item review submission.

Use [the preparation section](references/multi-item-submissions.md#prepare-every-item) for Game Center item preparation or attachment blockers. Use that reference's assembly and submission sections only after the app version is staged and the multi-item lane is selected. Switch to `asc-submission-health` for other validation blockers, a stuck submission, cancellation, or retry decisions.

# asc RevenueCat catalog sync

Use this skill to keep App Store Connect (ASC) and RevenueCat aligned, including creating missing ASC items and mapping them to RevenueCat resources.

## When to use
- You want to bootstrap RevenueCat from an existing ASC catalog.
- You want to create missing ASC subscriptions/IAPs, then map them into RevenueCat.
- You need a drift audit before release.
- You want deterministic product mapping based on identifiers.

## Preconditions
- `asc` authentication is configured (`asc auth login` or `ASC_*` env vars).
- RevenueCat MCP server is configured and authenticated.
- In Cursor and VS Code, OAuth auth is available for RevenueCat MCP. API key auth is also supported.

# asc screenshot resize

Use this skill to prepare screenshots for App Store Connect. Do not rely on a hard-coded dimension table in this skill; the CLI owns the current size matrix.

## Source of truth

Always discover current accepted sizes from `asc` first:

```bash
asc screenshots sizes --output table
asc screenshots sizes --all --output table
```

For local validation before upload:

# asc screenshots pipeline (xcodebuild -> AXe -> frame -> asc)

Use this skill for agent-driven screenshot workflows where the app is built and launched with Xcode CLI tools, UI is driven with AXe, and screenshots are uploaded with `asc`.

## Current scope
- Implemented now: build/run, AXe plan capture, frame composition, and upload.
- Device discovery is built-in via `asc screenshots list-frame-devices`.
- Local screenshot automation commands are experimental in asc cli.
- Framing is pinned to Koubou `0.20.0` for deterministic output.
- Feedback/issues: https://github.com/rorkai/App-Store-Connect-CLI/issues/new/choose

## Defaults
- Settings file: `.asc/shots.settings.json`
- Capture plan: `.asc/screenshots.json`

# asc signing setup

Use this skill when you need to create or renew signing assets for iOS/macOS apps.

## Preconditions
- Auth is configured (`asc auth login` or `ASC_*` env vars).
- You know the bundle identifier and target platform.
- You have a CSR file for certificate creation, or you will let `asc certificates create --generate-csr` create one.

## Workflow
1. Create or find the bundle ID:
   - `asc bundle-ids list --paginate`
   - `asc bundle-ids create --identifier "com.example.app" --name "Example" --platform IOS`
2. Configure bundle ID capabilities:

# App Store submission health

Use this skill to explain why a release cannot proceed and to manage an existing review submission. Hand healthy release execution back to `asc-release-flow`.

## Ownership boundary

This skill owns:

- readiness validation and blocker diagnosis;
- public-API, web-session, and manual repair routing;
- review status and history;
- cancellation and retry decisions.

Use `asc-release-flow` for staging, upload, publication, and submission. Switching skills continues the current task with its resolved targets, authorization, and verified progress; it does not require the user to restart the workflow. Continue authorized repairs and return to release execution when healthy. Ask for new authority only when a repair exceeds scope.

# asc subscription localization

Use this skill to bulk-create or bulk-update display names and, where supported,
descriptions for subscriptions, subscription groups, and in-app purchases across
all App Store Connect locales. This eliminates the tedious manual process of
clicking through each language in App Store Connect to set the same display
name.

## Preconditions
- Auth configured (`asc auth login` or `ASC_*` env vars).
- Know your app ID (`ASC_APP_ID` or `--app`).
- Subscription groups and subscriptions already exist.

## Choose the API scope first

# asc TestFlight orchestration

Use this skill when managing TestFlight testers, groups, and build distribution.

## Export current config
- `asc testflight config export --app "APP_ID" --output "./testflight.yaml"`
- Include builds/testers:
  - `asc testflight config export --app "APP_ID" --output "./testflight.yaml" --include-builds --include-testers`

## Manage groups and testers
- Groups:
  - `asc testflight groups list --app "APP_ID" --paginate`
  - `asc testflight groups create --app "APP_ID" --name "Beta Testers"`
  - A group's builds and testers: `asc testflight groups builds list --group-id "GROUP_ID" --paginate` and `asc testflight groups testers list --group-id "GROUP_ID" --paginate`

# asc wall submit

Use this skill to add or update a Wall of Apps entry with the built-in CLI flow.

## When to use

- User wants to submit an app to the Wall of Apps
- User wants to update an existing Wall of Apps entry
- User asks for the exact Wall submission flow

## Required inputs

Use one of these input paths:

# asc What's New Writer

Generate engaging, localized release notes from flexible input. Optionally pair with promotional text updates.

## Preconditions

- Metadata pulled locally into canonical files via `asc metadata pull --app "APP_ID" --version "1.2.3" --dir "./metadata"`. OR: user provides keywords manually.
- Auth configured for upload (`asc auth login` or `ASC_*` env vars).
- The **primary locale** is `en-US` unless the user specifies otherwise.

## Before You Start

1. Read `references/release_notes_guidelines.md` for tone, structure, and examples.
2. Identify the **latest version directory** under `metadata/version/` (highest semver). Use this for all metadata reads.

# asc workflow

Use this skill when you need lane-style automation inside the CLI using:

- `asc workflow validate`
- `asc workflow list`
- `asc workflow run`

Workflows are repo-local automation files. They run trusted shell commands, stream step output to stderr, and keep stdout as machine-readable JSON.

## Command discovery

Always verify flags with:

# Xcode build and export

Use this skill when you need to build an app from source and prepare it for App Store Connect. Prefer `asc xcode archive` and `asc xcode export` over raw `xcodebuild` recipes when they fit the project.

## Preconditions

For a prepared xtool package on Linux, use [portable iOS builds](references/portable-ios.md)
instead of the Xcode commands below. That workflow has a narrower project and signing contract.

- Xcode and command line tools are installed.
- Signing identity and provisioning profiles are available, or automatic signing is enabled.
- App Store Connect auth is configured when upload or build lookup is needed.

## Manage version and build numbers