appstore-release

Files (1)

• SKILL.md

SKILL.md (first lines)

# App Store Connect: archive, upload, submit

## Credentials

`cpm creds setup appstore` asks for each one and says where it lives:

| Name | Where to get it |
|---|---|
| `ASC_BUNDLE_ID` | The app target's bundle id, exactly (capitals matter). Or pass `--bundle-id`. |
| `ASC_KEY_ID` | App Store Connect > Users and Access > Integrations > **Team Keys**. Create one with the **Admin** or **App Manager** role (Developer cannot create versions or submit). |
| `ASC_ISSUER_ID` | Shown above the key list on the same page. One per team. |
| `ASC_KEY_PATH` | The `AuthKey_<id>.p8`. Apple lets you download it **once**, at creation. Lost it: revoke and make a new key. `cpm creds` copies it into `~/.config/cpm/<project>/keys/`. |
| `ASC_TEAM_ID` | Optional. Only asked when the app target has no `DEVELOPMENT_TEAM`. |

Environment variables of the same names win over the store (CI). Needs
`pip3 install 'pyjwt[crypto]' certifi` in the Python that runs `cpm`.

## Commands

```bash
cpm appstore status                           # versions + states, open submissions, recent builds (read-only)
cpm appstore version                          # app target's MARKETING_VERSION (offline)
cpm appstore build-number                     # highest uploaded build + 1
cpm appstore release                          # dry run: checks + plan, changes nothing
cpm appstore release --commit                 # archive, upload, wait, attach, What's New, submit
cpm appstore release --commit --replace-in-review   # cancel what is in review, ship this instead
cpm appstore release --commit --archive <path>.xcarchive   # reuse an archive (after a timeout)
cpm appstore release --commit --skip-upload   # already uploaded: wait, attach, submit
cpm appstore release --commit --no-submit     # stop after attaching; submit by hand
cpm appstore release --commit --testflight    # archive + upload only: a TestFlight build, even while a version is in review
cpm appstore metadata --spec listing.json    # preview localized description, keywords and promotional text
cpm appstore metadata --spec listing.json --backup before.json --commit
cpm appstore submit --version 1.2.3 --build 42          # inspect an existing ready review basket
cpm appstore submit --version 1.2.3 --build 42 --commit # submit it without rebuilding or replacing assets
cpm appstore experiment --spec round.json [--out result.json] [--commit] # create/resume a draft screenshot test
cpm appstore product-pages --spec pages.json --out result.json [--commit] # localized campaign page drafts
cpm appstore page-artwork --spec artwork.json --out artwork-result.json [--commit] # draft CPP header/search and inherited previews
cpm appstore prices --spec ladder.json [--out ios.json] [--markdown table.md] [--commit]   # reprice from a spec
```

Discovered, overridable: `--repo` (git toplevel), `--workspace`/`--xcodeproj`
(the only one; not `--project`, which `cpm` reads as the credentials project), `--scheme` (named after the project, or the only shared one),
`--team-id` (the app target's `DEVELOPMENT_TEAM`), `--notes-dir`
(`<repo>/release-notes`), `--build-dir` (`<tmp>/cpm-appstore/<scheme>`).
`--no-em-dash` refuses What's New containing an em dash (house style).

## Order

1. Bump `MARKETING_VERSION` on the app target in Xcode. That is the only place.
2. Write `release-notes/<version>/en-US.txt` (required, the fallback for every
   store locale) plus `<locale>.txt` or `<language>.txt` for others. Max 4000
   characters each; user-facing words, no internals.
3. `cpm appstore release` and read the plan: version, build, scheme, team, which
   store version it will reuse, rename or create.
4. `cpm appstore release --commit`. Processing takes 5 to 45 minutes; it waits.
5. `cpm appstore status` to confirm `WAITING_FOR_REVIEW`.

Never run `--commit` on an agent's own initiative: it builds, uploads and submits.

## Localized listing text and an existing review basket

`metadata` accepts JSON with `bundleId`, `platform`, `version`, and `localizations`.
Each locale key contains any of `description`, `keywords`, `promotionalText`.
It updates only those fields on existing locales, with no fallback translation,
build attachment, image change or automatic submission. The version must be
editable or `READY_FOR_REVIEW`. `--commit` requires a fresh backup path; it saves
the original locale records, checks for concurrent text edits, and reads back
each patch. Keep the reviewed spec in the app repo and backups outside it.

For search, use relevant native-language terms and avoid repeating the app name,
keywords already in the title/subtitle, competitor brands or duplicate terms.
Use plain text descriptions with natural search phrases and accurate features.
Promotional text supports conversion; Apple says it does not affect search ranking.
Validate description at 4,000 characters, promotional text at 170 characters,
and keywords conservatively at 100 UTF-8 bytes, per the
[platform version reference](https://developer.apple.com/help/app-store-connect/reference/app-information/platform-version-information).
Apple's [product page guidance](https://developer.apple.com/app-store/product-page/)
describes keyword selection and promotional text. Do not claim measured search
volume or ranking gains without data.

When the user has already added a version for review, `submit` verifies the
explicit version and valid attached build, finds its ready basket, and refuses
extra/unrelated items. Run its dry run before `--commit`, then check `status`.
It does not create a basket, edit text, attach builds or cancel another review.

## Screenshot theme tests (`experiment`)

Product Page Optimization supports at most three treatments against the original
page per test. Apple also refuses a second draft while one is in
`PREPARE_FOR_SUBMISSION`. Prepare later rounds locally and create them when the
existing round is finished, with one running at a time.
Keep app captures, captions and ordering identical when testing artwork colours;
an artwork theme does not prove that the pictured app UI uses that theme.

The experiment JSON names `bundleId`, `name`, `platform: "IOS"`,
`trafficProportion` and `treatments`. Each treatment has a unique `name` and
`screenshots: [{"locale":"en-US","display":"APP_IPHONE_67","folder":"shots"}]`.
Folders resolve relative to the JSON. All treatments target the same locales and
display sizes. With three treatments and 75% traffic, each treatment gets 25% and
the original gets 25%.

Run the dry run before `--commit`. The command creates only drafts, requires a
live iOS version, refuses a started/submitted test, and resumes only matching
named drafts whose screenshot order and checksums match a prefix of the local
files. It reads every uploaded file back and requires `COMPLETE`. Apple populates
new treatment localizations with copies of the live screenshot sets. To replace
these, use `--replace-inherited`: it checks that draft and live IDs differ and
that filenames, sizes and checksums match before deleting only those draft
copies. At `UPLOAD_COMPLETE`, Apple may return a null checksum; wait for
`COMPLETE` before comparing hashes rather than uploading the file again.
The live set is read back afterward. The command never changes the app
version, original page or review basket. If a PUT is interrupted, the final asset may remain `AWAITING_UPLOAD`. The
command checks the prior file prefix, name and byte count before resuming that
reservation. Apple may omit transfer URLs on GET; then only that verified empty
reservation is replaced. Uploaded or processing files are never reset. Transfer
PUTs retry transient network failures without creating duplicate reservations.

Start the draft in App Store Connect after its assets pass review. If screenshots
show an upcoming feature, wait until that app version is live. Releasing new

From tirupati17/cpm, MIT.

More from tirupati17/cpm