asc-cli: a Swift App Store Connect CLI whose JSON answers carry the next command

Responses carry their own next commands, and some only appear when the version is editable

The distinctive idea is CAEOAS, short for Commands As the Engine Of Application State, a play on HATEOAS in REST. Each response embeds an affordances object holding commands that are ready to run, so an agent does not have to memorise the command tree. The versions example shows the shape:

asc versions list --app-id app-abc

The returned version has an id, a versionString of 2.1.0, a state of PREPARE_FOR_SUBMISSION and an isEditable flag. Under affordances you get `listLocalizations`, `checkReadiness`, and `submitForReview`. The last one is annotated as present only when isEditable == true. The consequence is practical: the absence of a submit command in the output is itself a signal that the version is locked, and an agent that waits for the key to appear will not try to submit a version that cannot be submitted.

Nothing works until an API key file and two identifiers are in place

Every command talks to Apple through an App Store Connect API key, which you create on Apple's integrations page. Installation is a single Homebrew formula, and login takes three values:

brew install asccli

asc auth login \
  --key-id YOUR_KEY_ID \
  --issuer-id YOUR_ISSUER_ID \
  --private-key-path ~/.asc/AuthKey_XXXXXX.p8

The key id and issuer id identify the key, and the path points at the downloaded .p8 private key file. Multiple accounts and environment variables for CI are handled in a separate auth page under docs/features. That makes the .p8 file the one thing you must protect and distribute to CI yourself, since the tool has nothing to run without it.

asc init pins an app, but only for the commands that take --app-id

Most commands act on an app, so repeating its identifier gets old. Two commands handle that:

asc apps list          # find your app ID
asc init --app-id <id> # pin it — skip --app-id on every future command

`asc apps list` shows the identifiers and `asc init` records the one you choose, after which you can drop `--app-id`. The pin covers the app level only. Other identifiers still appear explicitly in the examples, for instance `--version-id v1` in the affordance commands. So the pin saves typing on the first step, and the version-level commands still take the id from the previous response. That is exactly what the embedded affordances are for.

JSON is the default output, with table, markdown, a TUI and a REST server beside it

Machine-readable output is the default. Add `--output table` or `--output markdown` when a person is reading, or run `asc tui` to browse interactively. The `asc web-server` command serves the same commands as a REST API, which matters if the consumer is a service and not a shell. Every command and flag is listed in docs/commands.md and available through `asc <command> --help`.

The Makefile shows how that reference is kept honest: the `docs` target runs `python3 scripts/gen-docs.py .build/debug/asc` to regenerate docs/commands.md and docs/README.md, with a comment that they must never be edited by hand. A separate `check-docs` target runs `python3 scripts/check-docs.py`. If you contribute, change the command and regenerate, because a hand edit to those two files will be overwritten.

Iris commands reach features with no public API, so they stand on different ground

Most of the coverage table maps to Apple's public API: apps and versions, builds, TestFlight, metadata, screenshots, monetization, code signing, customer reviews, team members, Xcode Cloud, sales and finance reports, App Clips and Game Center. One row is different. Iris is labelled a private API and covers web UI features that have no public API: creating apps and reading App Review's rejection messages.

The consequence is about expectations. Everything else is built on the documented key-based interface, while Iris reaches behaviour that Apple has not published as an API. Treat those commands as the part most exposed to change, and do not build an unattended pipeline around reading rejection messages without a manual fallback. The feature pages are iris and resolution-center under docs/features.

App Shots generates screenshots with an AI step that needs its own setup

App Shots is the AI screenshot generator. Its row lists templates, gallery sets, plugin themes and Gemini enhancement, with feature pages named app-shots and app-shots-themes. The repository carries example material in demo/asc-app-shots/ and demo/plugins/, which is where to look for a working layout.

The row says Gemini enhancement, so that step depends on Google's model and whatever access it needs. The App Store Connect key alone is not described as covering it. Separately, the screenshot system proper uploads once to an asset library and places the image on every localization, while legacy screenshot and preview sets remain as a second path. Choose one workflow deliberately, because they are listed as distinct features with distinct docs.

Swift sources, the ASCKit library, and a release stream that moved three times in a month

The repository is a Swift package: Package.swift, Package.resolved, Sources/ and Tests/. The Makefile exposes `swift build`, `swift test`, `swift format --in-place --recursive Sources Tests`, and `swift run asc $(ARGS)`. Its lint target runs `swift package diagnose-api-breaking-changes`, though with `|| true` the step does not fail the build. A separate document covers using ASCKit as a Swift package inside your own tool.

The latest release in the data is v0.18.7 on 2026-11-01, preceded by v0.18.6 on 2026-10-11 and v0.18.5 on 2026-10-03, and the last push was 2026-11-01. The version number is still below 1.0, so pin the version you script against and read the changelog before updating.

Editorial conclusion

Use asc-cli if you ship iOS or macOS apps and want releases, TestFlight and metadata scripted from a terminal or CI, especially with an agent reading the JSON. Do not rely on it for the Iris commands as if they were Apple's public API, and check the docs index for the exact flags of any area you depend on.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. tddworks/asc-cli on GitHub