Skip to main content
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
1

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
2

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 get detailed information: 
asc apps get --app "123456789" --output json --pretty

​
Set a default app

Avoid typing --app repeatedly: 
export ASC_APP_ID="123456789"
asc apps get  # 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 feedback --app "123456789" --limit 10

​
Fetch crash reports

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

​
Common workflows

​
Upload a build to TestFlight

asc builds upload \
  --app "123456789" \
  --file "/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 beta-groups list --app "123456789"

​
Add a build to a beta group

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

​
Validate an App Store version

Before submitting for review: 
asc validate --app "123456789" --version "1.2.3"

​
Submit for App Store review

asc submit --app "123456789" --version "1.2.3"
Use --confirm to skip confirmation prompts in scripts: asc submit --app "123456789" --version "1.2.3" --confirm

​
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: 
asc apps list --output table
Human-readable tabular output with borders.

​
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 list --app "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

Ensure asc is in your PATH:
which asc
If empty, add the installation directory to your shell profile:
export PATH="$HOME/.local/bin:$PATH"
Verify your credentials:
asc auth status --validate
Run the doctor to diagnose issues:
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:
export ASC_TIMEOUT="120s"
asc builds upload --app "123456789" --file large.ipa
For uploads, use ASC_UPLOAD_TIMEOUT:
export ASC_UPLOAD_TIMEOUT="300s"

​
Get help