llms.txt

# App Store Connect CLI (`asc`)

`asc` is an unofficial, fast, scriptable command-line tool for the App Store
Connect API.

## Project snapshot

- Language: Go
- Distribution: single binary (`asc`)
- Scope: apps, builds, TestFlight, submissions, metadata, signing, analytics,
  reports, and workflow automation
- Output model: JSON-first (minified by default)
- CLI style: explicit long flags (`--app`, `--output`) and non-interactive
  behavior (`--confirm` for destructive actions)

## Canonical entry points

- Repository: https://github.com/rudrankriyam/App-Store-Connect-CLI
- Website/docs: https://asccli.sh
- Command discovery:
  - `asc --help`
  - `asc <command> --help`
  - `asc <command> <subcommand> --help`

## Install

- Homebrew (recommended):
  - `brew install asc`
- Install script (macOS/Linux):
  - `curl -fsSL https://asccli.sh/install | bash`
- Source/contributor setup:
  - see `CONTRIBUTING.md`

## Quick start

- Authenticate with an API key:
  - `asc auth login --name "MyApp" --key-id "ABC123" --issuer-id "DEF456" --private-key /path/to/AuthKey.p8`
- First command:
  - `asc apps list --output table`

Generate keys at:
https://appstoreconnect.apple.com/access/integrations/api

## Common workflows

- TestFlight feedback and crashes:
  - `asc feedback --app "123456789" --paginate`
  - `asc crashes --app "123456789" --sort -createdDate --limit 10`
- Builds and distribution:
  - `asc builds upload --app "123456789" --ipa "/path/to/MyApp.ipa"`
  - `asc testflight builds list --app "123456789" --output table`
- Validate and submit:
  - `asc validate --app "123456789" --version "1.2.3"`
  - `asc submit --app "123456789" --version "1.2.3"`
- Metadata/localization:
  - `asc localizations list --app "123456789"`
  - `asc app-info get --app "123456789" --output json --pretty`
- Screenshots/media:
  - `asc screenshots list --app "123456789"`
  - `asc video-previews list --app "123456789"`
- Signing and bundle IDs:
  - `asc certificates list`
  - `asc profiles list`
  - `asc bundle-ids list`
- Workflow automation:
  - `asc workflow run release`

## CI/CD integrations

- GitHub Actions:
  - `uses: rudrankriyam/setup-asc@v1`
- GitLab components:
  - `gitlab.com/rudrankriyam/asc-ci-components/run@main`
- Bitrise:
  - `git::https://github.com/rudrankriyam/steps-setup-asc.git@main`
- CircleCI:
  - https://github.com/rudrankriyam/asc-orb

## Output and pagination patterns

- Parse JSON in automation:
  - `asc apps list | jq '.data[] | {id: .id, name: .attributes.name}'`
- Fetch all pages:
  - `asc apps list --paginate`
- Human-friendly output:
  - `asc builds list --app "APP_ID" --output table`

## Authentication and environment variables

`asc` uses App Store Connect API key auth with keychain storage (when
available), plus config/env fallback.

Core auth variables:

- `ASC_KEY_ID`
- `ASC_ISSUER_ID`
- `ASC_PRIVATE_KEY_PATH`
- `ASC_PRIVATE_KEY`
- `ASC_PRIVATE_KEY_B64`
- `ASC_BYPASS_KEYCHAIN`
- `ASC_STRICT_AUTH`

Common operational variables:

- `ASC_APP_ID`
- `ASC_VENDOR_NUMBER`
- `ASC_TIMEOUT`
- `ASC_TIMEOUT_SECONDS`
- `ASC_UPLOAD_TIMEOUT`
- `ASC_UPLOAD_TIMEOUT_SECONDS`
- `ASC_DEBUG` (set to `api` for HTTP request/response logs)
- `ASC_DEFAULT_OUTPUT` (`json`, `table`, `markdown`, `md`)

Output defaults are TTY-aware when `ASC_DEFAULT_OUTPUT` is unset:
- interactive terminal (TTY) => `table`
- non-interactive/piped output => `json`

Explicit `--output` always overrides `ASC_DEFAULT_OUTPUT` and TTY-aware defaults.

## Development and local validation

- Build:
  - `make tools`
  - `make build`
- Format:
  - `make format`
- Lint:
  - `make lint`
- Tests (always bypass keychain in test runs):
  - `ASC_BYPASS_KEYCHAIN=1 make test`
- Command docs check:
  - `make check-command-docs`

## Source-of-truth docs in this repo

- `README.md`
- `AGENTS.md`
- `CONTRIBUTING.md`
- `docs/COMMANDS.md`
- `docs/API_NOTES.md`
- `docs/TESTING.md`
- `docs/openapi/latest.json`
- `docs/openapi/paths.txt`

## Implementation notes for agents/tools

- Use explicit flags over short aliases.
- Prefer JSON output in automation paths.
- Avoid interactive prompts in scripts; pass required confirmation flags.
- Validate endpoint/attribute support against `docs/openapi/latest.json` before
  shipping new API-facing flags.

## Keywords

App Store Connect, TestFlight, Xcode Cloud, code signing, provisioning
profiles, certificates, analytics, CI/CD, Go CLI, Apple platform releases.