Quickstart

Get started with the App Store Connect CLI in minutes

This guide walks you through your first asc commands, from authentication to making your first API call.

Prerequisites

Before starting, make sure you have:

Installed asc (Installation guide)
Generated App Store Connect API credentials (Authentication guide)
A .p8 private key file from App Store Connect

Step 1: Authenticate

Store your API credentials using asc auth login:

asc auth login \
  --name "MyApp" \
  --key-id "ABC123DEFG" \
  --issuer-id "12345678-abcd-1234-abcd-123456789012" \
  --private-key ~/.asc/AuthKey_ABC123.p8

Replace placeholders

--name: A friendly name for this key (e.g., “Personal”, “WorkProject”)
--key-id: Your 10-character Key ID from App Store Connect
--issuer-id: Your Issuer ID (UUID format)
--private-key: Path to your .p8 file

Verify storage

asc auth status

Expected output:

Credential storage: System Keychain
Location: system keychain

Stored credentials:
Name    Key ID      Default  Stored In
MyApp   ABC123DEFG  yes      keychain

By default, credentials are stored in your system keychain (macOS Keychain, Windows Credential Manager, or Linux Secret Service). Use --bypass-keychain to store in a config file instead.

Step 2: List your apps

Fetch all apps associated with your account:

asc apps list

Sample output (interactive terminal):

┌────────────┬──────────────┬─────────────────┬────────────────┐
│ ID         │ Name         │ Bundle ID       │ SKU            │
├────────────┼──────────────┼─────────────────┼────────────────┤
│ 123456789  │ My Great App │ com.example.app │ MY_GREAT_APP_1 │
│ 987654321  │ Another App  │ com.example.two │ ANOTHER_APP_2  │
└────────────┴──────────────┴─────────────────┴────────────────┘

When piped or in CI, asc automatically outputs JSON. Try: asc apps list | jq

Get JSON output explicitly

asc apps list --output json --pretty

Output:

{
  "data": [
    {
      "id": "123456789",
      "type": "apps",
      "attributes": {
        "name": "My Great App",
        "bundleId": "com.example.app",
        "sku": "MY_GREAT_APP_1",
        "primaryLocale": "en-US"
      }
    }
  ]
}

Step 3: Explore a specific app

Use the app ID from the previous step to view detailed information:

asc apps view --id "123456789" --output json --pretty

Set a default app

A default app helps with commands that accept --app:

export ASC_APP_ID="123456789"
asc apps info view  # Uses ASC_APP_ID automatically

Or add to your shell profile (~/.bashrc, ~/.zshrc, etc.):

echo 'export ASC_APP_ID="123456789"' >> ~/.zshrc

Step 4: Fetch builds

List recent builds for your app:

asc builds list --app "123456789" --sort -uploadedDate --limit 5

Sample output:

┌─────────────┬─────────┬──────────┬─────────────────────┬──────────────────┐
│ ID          │ Version │ Build    │ Uploaded            │ Processing State │
├─────────────┼─────────┼──────────┼─────────────────────┼──────────────────┤
│ abc123      │ 1.2.3   │ 45       │ 2026-03-04 10:30:00 │ VALID            │
│ def456      │ 1.2.2   │ 44       │ 2026-03-03 15:20:00 │ VALID            │
│ ghi789      │ 1.2.1   │ 43       │ 2026-03-02 09:15:00 │ VALID            │
└─────────────┴─────────┴──────────┴─────────────────────┴──────────────────┘

Use --paginate to fetch all pages automatically: asc builds list --app "123456789" --paginate

Step 5: Check TestFlight feedback

View feedback from beta testers:

asc testflight feedback list --app "123456789" --limit 10

Fetch crash reports

asc testflight crashes list --app "123456789" --sort -createdDate --limit 5

Common workflows

Upload a build to TestFlight

asc builds upload \
  --app "123456789" \
  --ipa "/path/to/MyApp.ipa"

Build uploads can take several minutes depending on file size and network speed. The CLI shows progress and waits for processing to complete.

List TestFlight beta groups

asc testflight groups list --app "123456789"

Add a build to a beta group

asc builds add-groups \
  --build-id "abc123" \
  --group "def456"

Validate an App Store version

Before submitting for review:

asc validate --app "123456789" --version "1.2.3"

Publish to the App Store

asc publish appstore --app "123456789" --ipa "./MyApp.ipa" --version "1.2.3" --submit --confirm

The canonical App Store publish path is asc publish appstore ... --submit --confirm. Use asc validate, asc submit status, or asc submit cancel for readiness and submission lifecycle follow-up work.

Explore commands

asc is self-documenting. Use --help at any level:

asc --help

Sample --help output:

USAGE
  asc builds list [flags]

FLAGS
  --app string           App ID (required)
  --sort string          Sort results (e.g., -uploadedDate)
  --limit int            Limit results (default: 20)
  --paginate             Fetch all pages
  --output string        Output format: table, json, markdown
  --pretty               Pretty-print JSON output

EXAMPLES
  asc builds list --app "123456789"
  asc builds list --app "123456789" --sort -uploadedDate --limit 10
  asc builds list --app "123456789" --paginate --output json

Output formats

asc supports multiple output formats:

table (default in TTY)
json (default in pipes/CI)
json --pretty
markdown

asc apps list --output table

Human-readable tabular output with borders.

asc apps list --output json

Minified JSON for machine parsing.

asc apps list --output json --pretty

Indented JSON for readability.

asc apps list --output markdown

Markdown-formatted tables.

Set a global default

export ASC_DEFAULT_OUTPUT=json
asc apps list  # Always outputs JSON

Explicit flags always override defaults:

ASC_DEFAULT_OUTPUT=json asc apps list --output table

Scripting tips

Exit codes

asc uses standard exit codes:

0: Success
1: Runtime error (API failure, network issue, etc.)
2: Usage error (invalid flags, missing arguments)

if asc apps view --id "123456789" > /dev/null 2>&1; then
  echo "App found"
else
  echo "Error: $?"
fi

Parse JSON output with jq

# Extract app names
asc apps list --output json | jq -r '.data[].attributes.name'

# Filter by bundle ID
asc apps list --output json | jq '.data[] | select(.attributes.bundleId == "com.example.app")'

# Count builds
asc builds list --app "123456789" --output json | jq '.data | length'

Pagination

Manual pagination:

# First page
asc builds list --app "123456789" --limit 20

# Next page (use the 'next' link from JSON output)
asc builds list --app "123456789" --limit 20 --next "CURSOR_VALUE"

Automatic pagination:

asc builds list --app "123456789" --paginate

Environment variables

Common environment variables for convenience:

export ASC_APP_ID="123456789"              # Default app ID
export ASC_DEFAULT_OUTPUT="json"           # Default output format
export ASC_TIMEOUT="90s"                   # Request timeout
export ASC_DEBUG="api"                     # Enable API debug logging

See Environment Variables Reference for the complete list.

Next steps

Command reference

Browse all available commands and flags

CI/CD integration

Automate workflows in GitHub Actions, GitLab CI, and more

Workflows

Create multi-step automation with asc workflow

Guides

Real-world examples for common tasks

Troubleshooting

Command not found: asc

Ensure asc is in your PATH:

which asc

If empty, add the installation directory to your shell profile:

export PATH="$HOME/.local/bin:$PATH"

Authentication failed

Verify your credentials:

asc auth status --validate

Run the doctor to diagnose issues:

asc auth doctor

API rate limits

App Store Connect enforces rate limits. If you hit them:

Reduce request frequency
Use --limit to fetch fewer results
Cache API responses locally

The CLI automatically retries rate-limited requests with exponential backoff.

Network timeouts

Increase the timeout for slow connections:

export ASC_TIMEOUT="120s"
asc builds upload --app "123456789" --ipa large.ipa

For uploads, use ASC_UPLOAD_TIMEOUT:

export ASC_UPLOAD_TIMEOUT="300s"

Get help

Built-in docs: asc --help or asc <command> --help
GitHub Issues: Report bugs or request features
Discussions: Ask questions and share workflows

Getting Started

Core Concepts

Guides

CI/CD Integration

Configuration

Quickstart

Quickstart

Prerequisites

Step 1: Authenticate

Step 2: List your apps

Get JSON output explicitly

Step 3: Explore a specific app

Set a default app

Step 4: Fetch builds

Step 5: Check TestFlight feedback

Fetch crash reports

Common workflows

Upload a build to TestFlight

List TestFlight beta groups

Add a build to a beta group

Validate an App Store version

Publish to the App Store

Explore commands

Output formats

Set a global default

Scripting tips

Exit codes

Parse JSON output with jq

Environment variables

Next steps

Command reference

CI/CD integration

Workflows

Guides

Troubleshooting

Get help

Getting Started

Core Concepts

Guides

CI/CD Integration

Configuration

​Quickstart

​Prerequisites

​Step 1: Authenticate

​Step 2: List your apps

​Get JSON output explicitly

​Step 3: Explore a specific app

​Set a default app

​Step 4: Fetch builds

​Step 5: Check TestFlight feedback

​Fetch crash reports

​Common workflows

​Upload a build to TestFlight

​List TestFlight beta groups

​Add a build to a beta group

​Validate an App Store version

​Publish to the App Store

​Explore commands

​Output formats

​Set a global default

​Scripting tips

​Exit codes

​Parse JSON output with jq

​Pagination

​Environment variables

​Next steps

Command reference

CI/CD integration

Workflows

Guides

​Troubleshooting

​Get help

Quickstart

Prerequisites

Step 1: Authenticate

Step 2: List your apps

Get JSON output explicitly

Step 3: Explore a specific app

Set a default app

Step 4: Fetch builds

Step 5: Check TestFlight feedback

Fetch crash reports

Common workflows

Upload a build to TestFlight

List TestFlight beta groups

Add a build to a beta group

Validate an App Store version

Publish to the App Store

Explore commands

Output formats

Set a global default

Scripting tips

Exit codes

Parse JSON output with jq

Pagination

Environment variables

Next steps

Troubleshooting

Get help