Skip to content

quickstart.mdx

Latest commit

 

History

History
444 lines (322 loc) · 11.3 KB

quickstart.mdx

File metadata and controls

444 lines (322 loc) · 11.3 KB
Raw

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:

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
* `--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 ```bash theme={null} 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:

```bash List all commands theme={null} asc --help ``` 
asc builds --help
asc builds list --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:

```bash theme={null} asc apps list --output table ``` 
Human-readable tabular output with borders.
```bash theme={null} asc apps list --output json ``` 
Minified JSON for machine parsing.
```bash theme={null} asc apps list --output json --pretty ``` 
Indented JSON for readability.
```bash theme={null} 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

Browse all available commands and flags Automate workflows in GitHub Actions, GitLab CI, and more Create multi-step automation with `asc workflow` Real-world examples for common tasks

Troubleshooting

Ensure `asc` is in your `PATH`: 
```bash  theme={null}
which asc
```

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

```bash  theme={null}
export PATH="$HOME/.local/bin:$PATH"
```
Verify your credentials: 
```bash  theme={null}
asc auth status --validate
```

Run the doctor to diagnose issues:

```bash  theme={null}
asc auth doctor
```
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.
Increase the timeout for slow connections: 
```bash  theme={null}
export ASC_TIMEOUT="120s"
asc builds upload --app "123456789" --ipa large.ipa
```

For uploads, use `ASC_UPLOAD_TIMEOUT`:

```bash  theme={null}
export ASC_UPLOAD_TIMEOUT="300s"
```

Get help