# asc-cli: App Store Connect from the Terminal and from AI Agents

> A Swift CLI that wraps App Store Connect, TestFlight, subscriptions and screenshots, with JSON output and CAEOAS affordances meant to be driven by agents. It installs through Homebrew and pins app context in .asc/project.json.

**tddworks/asc-cli** — App Store Connect from your terminal & Agents. A Swift CLI for managing your iOS and macOS apps on App Store Connect. Submit versions, manage screenshots, track builds — with full AI-agent support via CAEOAS affordances.

- Repository: https://github.com/tddworks/asc-cli
- Website: http://asccli.app
- Stars: 373 · Forks: 30
- Language: Swift
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/tddworks-asc-cli

## The release workflow asc-cli puts on the command line

App Store Connect work happens in a browser or through a raw HTTP client. asc-cli turns it into subcommands: apps and versions, builds and TestFlight distribution, per-locale metadata, screenshots and app previews, in-app purchases and subscriptions, code signing assets, customer reviews, App Clips, Game Center, and reports. The README frames the tool as an App Store Command Center and states that it outputs structured JSON so AI agents can drive the full release workflow. That last part is the distinguishing claim. Most CLI wrappers stop at human-readable output; this one is designed so a model can read the response and pick the next action without knowing the command tree in advance. The audience is iOS and macOS developers who already ship through CI, and the secondary audience is anyone building an agent that touches release management. The requirements are macOS 13 or later and an App Store Connect API key; Swift 6.2 is needed only when building from source.

## How CAEOAS affordances change the agent loop

The README describes the agent support as JSON output with CAEOAS affordances, and says agents navigate without knowing the command tree. The concrete example given is IAP submission. After iris login, `asc iap list --app-id <id>` enriches each in-app purchase with the right submission affordance: `addToNextVersion` for queue-via-iris, `removeFromNextVersion` to dequeue, or `submit` for standalone review of an established app. The README states the agent reads one affordance and runs it, so it does not need to learn whether iris or the SDK applies to a given purchase. That is a real design decision, not marketing: the branching logic about which API accepts which operation lives in the CLI, and the agent only sees the resulting action name. Credentials resolve in a fixed order, `~/.asc/credentials.json` first and environment variables second, so a CI job can run on environment variables while a developer machine uses a named account. Project context is pinned separately: `asc init` writes to `.asc/project.json` and can auto-detect the app from a `.xcodeproj` bundle ID. Plugins are executables installed in `~/.asc/plugins/` for custom event handlers.

## Installing asc-cli and running a first command

Homebrew is the recommended path. The README gives a single formula name, so the install is one line and then a login. The login takes the key ID, the issuer ID and the path to the .p8 private key, and optionally a name alias that defaults to "default".

```bash
brew install asccli

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

After that, list your apps to find the numeric app ID, then pin it so later commands do not need `--app-id` on every call.

```bash
asc apps list
asc init --app-id <id>
```

The README also documents `asc init` with no arguments to auto-detect from a `.xcodeproj` bundle ID, and `asc init --name "My App"` to search by name. `asc init --app-id` is the only variant that needs no API call. If you prefer not to write a credentials file, the environment variables `ASC_KEY_ID`, `ASC_ISSUER_ID` and `ASC_PRIVATE_KEY_PATH` are supported, with `ASC_PRIVATE_KEY` as an alternative that takes PEM content directly. Building from source uses `swift build -c release` and copies `.build/release/asc` to `/usr/local/bin/`; the repository Makefile has `make build`, `make test`, `make format` and `make run` targets, and `make run` passes `$(ARGS)` through to the binary.

## The iris private API and the first-IAP gap

This is the most consequential limitation in the README, and it is stated plainly: the public App Store Connect API cannot submit the first in-app purchase for an app. Apple requires that submission to ride along with a new App Store version, and the README says the only path that accepts the flag is the iris private API, the one that powers the ASC web UI. asc-cli works around this by letting you sign in with an Apple ID instead of an API key. `asc iris auth login --apple-id you@example.com --interactive` prompts for the password and a two-factor code, then saves a session to `~/.asc/iris/session.json` that the README says lasts about 30 days. `asc iris status` verifies it and reports `source: "srpLogin"`. The trade-off is obvious and the README does not hide it: you are storing a cookie-based session for a private API, and that session expires, so a CI pipeline that depends on iris will break roughly monthly unless something refreshes it. The README does not document rollback of a submitted version, and it does not describe how to recover a failed iris session beyond logging in again with `asc iris auth login`. The README also notes iris is purely additive: CI scripts using the API key alone keep working unchanged, and `asc iris auth logout` clears the session.

## Where asc-cli is the wrong tool

The requirements section says macOS 13 or later, and the build path needs Swift 6.2. There is no Linux or Windows target in the README, so a release pipeline running on a Linux runner cannot use the binary as shipped. Screenshot generation is described as AI-powered, with single templates, gallery sets, plugin-provided themes covering colors, decorations and animations, and Gemini enhancement, plus a two-step ThemeDesign workflow the README says avoids extra AI calls on batch styling. That is a feature set with an external dependency baked in, and the README does not state which Gemini model or endpoint is used, or what happens when that call fails. If your team's policy forbids sending marketing screenshots to a third-party model, the App Shots commands are not for you even though the rest of the CLI is. Finally, the last push to the repository was on 2026-08-04, which is recent enough that the project is not dormant, but the README does not describe a release cadence or a support commitment, so anyone needing a vendor SLA should look elsewhere.

## asc-cli against fastlane and the raw API

The closest comparison in the Apple ecosystem is fastlane, which is the tool most iOS teams already have in their Gemfile. The difference in approach is the language and the integration surface. fastlane is Ruby, configured through a Fastfile and a set of actions, and its TestFlight and deliver lanes are mature. asc-cli is Swift, distributed as a compiled binary through Homebrew, and its stated design goal is structured JSON output that an agent can act on rather than a DSL a human writes. If your build already runs a Fastfile, replacing it means rewriting lanes into shell calls to `asc` subcommands, and the README does not claim feature parity with fastlane's plugin ecosystem. The other alternative is calling the App Store Connect API directly. That gives you full control and no third-party session handling, but you reimplement pagination, token generation and the per-resource quirks, and you lose the affordance layer that tells an agent which submission path applies. The iris login is the one capability that is hard to replicate yourself, because it depends on reverse-engineered private API behavior that the README says powers the web UI.

## Licence, upgrade cost and what to check before adopting

The repository is MIT licensed, which permits commercial use, modification and redistribution with the licence text preserved. That is the whole of the licence implication here; the README does not add any usage restriction, and nothing in it suggests a paid tier. The practical upgrade cost is different. Releases move quickly: v0.18.0 on 2026-05-13, v0.18.1 on 2026-05-31, v0.18.2 on 2026-07-16. Three minor releases in two months means command output and JSON shapes can shift between versions, and the README documents no deprecation policy or versioned output format. If you parse the JSON in an agent or a script, pin the Homebrew version and read CHANGELOG.md before bumping, because the README itself does not describe what changed between those releases. Credential storage is a second thing to review: `~/.asc/credentials.json` holds API key material and `~/.asc/iris/session.json` holds a roughly 30-day session cookie, and the README does not describe file permissions or encryption for either file.

## Conclusion

Adopt asc-cli if you already script App Store Connect releases, want JSON output an agent can consume, or need the iris private API path for first-time IAP submissions. Skip it if you are on Linux, or if you want a GUI and a vendor-supported SLA. Before committing, verify the private key path and issuer ID work with asc auth check, confirm your app ID is written into .asc/project.json by asc init, and read the iris section of the README to decide whether storing a session cookie in ~/.asc/iris/session.json fits your security posture.

## FAQ

### What is asc-cli?

It is a Swift command line tool for App Store Connect, covering builds, releases, TestFlight, subscriptions, screenshots and code signing. The README describes it as producing structured JSON so AI agents can drive the full release workflow.

### How do I install asc-cli?

The README recommends Homebrew with `brew install asccli`. Alternatively you can clone the repository, run `swift build -c release`, and copy `.build/release/asc` to `/usr/local/bin/`.

### Does asc-cli need an App Store Connect API key?

Yes for the public API. You run `asc auth login` with a key ID, issuer ID and the path to a .p8 private key, and credentials are saved to `~/.asc/credentials.json`. The iris private API instead uses an Apple ID sign-in with two-factor authentication.

### Can asc-cli submit an in-app purchase?

The README states the public App Store Connect API cannot submit the first IAP for an app, because Apple requires it to ride along with a new App Store version. Signing in through `asc iris auth login` unlocks that path and makes `asc iap list` return the right submission affordance per purchase.

### What does asc init do?

It pins app context to `.asc/project.json` so later commands do not need `--app-id`. It can auto-detect the app from a `.xcodeproj` bundle ID, search by name, or take an app ID directly, which is the only variant that makes no API call.

## Sources

- [License: MIT](https://github.com/tddworks/asc-cli/blob/main/LICENSE)
- [Project website](http://asccli.app)
- [README](https://github.com/tddworks/asc-cli/blob/main/README.md)
- [Releases](https://github.com/tddworks/asc-cli/releases)
- [tddworks/asc-cli on GitHub](https://github.com/tddworks/asc-cli)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tddworks-asc-cli