> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asccli.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

# 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:

* [x] Installed `asc` ([Installation guide](/installation))
* [x] Generated App Store Connect API credentials ([Authentication guide](/authentication))
* [x] A `.p8` private key file from App Store Connect

## Step 1: Authenticate

Store your API credentials using `asc auth login`:

```bash theme={null} theme={null}
asc auth login \
  --name "MyApp" \
  --key-id "ABC123DEFG" \
  --issuer-id "12345678-abcd-1234-abcd-123456789012" \
  --private-key ~/.asc/AuthKey_ABC123.p8
```

<Steps>
  <Step title="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
  </Step>

  <Step title="Verify storage">
    ```bash theme={null} 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
    ```
  </Step>
</Steps>

<Note>
  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.
</Note>

## Step 2: List your apps

Fetch all apps associated with your account:

```bash theme={null} theme={null}
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  │
└────────────┴──────────────┴─────────────────┴────────────────┘
```

<Tip>
  When piped or in CI, `asc` automatically outputs JSON. Try: `asc apps list | jq`
</Tip>

### Get JSON output explicitly

```bash theme={null} theme={null}
asc apps list --output json --pretty
```

Output:

```json theme={null} theme={null}
{
  "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:

```bash theme={null} theme={null}
asc apps view --id "123456789" --output json --pretty
```

### Set a default app

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

```bash theme={null} theme={null}
export ASC_APP_ID="123456789"
asc apps info view  # Uses ASC_APP_ID automatically
```

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

```bash theme={null} theme={null}
echo 'export ASC_APP_ID="123456789"' >> ~/.zshrc
```

## Step 4: Fetch builds

List recent builds for your app:

```bash theme={null} theme={null}
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            │
└─────────────┴─────────┴──────────┴─────────────────────┴──────────────────┘
```

<Note>
  Use `--paginate` to fetch all pages automatically: `asc builds list --app "123456789" --paginate`
</Note>

## Step 5: Check TestFlight feedback

View feedback from beta testers:

```bash theme={null} theme={null}
asc testflight feedback list --app "123456789" --limit 10
```

### Fetch crash reports

```bash theme={null} theme={null}
asc testflight crashes list --app "123456789" --sort -createdDate --limit 5
```

## Common workflows

### Upload a build to TestFlight

```bash theme={null} theme={null}
asc builds upload \
  --app "123456789" \
  --ipa "/path/to/MyApp.ipa"
```

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

### List TestFlight beta groups

```bash theme={null} theme={null}
asc testflight groups list --app "123456789"
```

### Add a build to a beta group

```bash theme={null} theme={null}
asc builds add-groups \
  --build-id "abc123" \
  --group "def456"
```

### Validate an App Store version

Before submitting for review:

```bash theme={null} theme={null}
asc validate --app "123456789" --version "1.2.3"
```

### Publish to the App Store

```bash theme={null} theme={null}
asc publish appstore --app "123456789" --ipa "./MyApp.ipa" --version "1.2.3" --submit --confirm
```

<Note>
  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.
</Note>

## Explore commands

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

<CodeGroup>
  ```bash List all commands theme={null} theme={null}
  asc --help
  ```

  ```bash Command group help theme={null} theme={null}
  asc builds --help
  ```

  ```bash Specific command help theme={null} theme={null}
  asc builds list --help
  ```
</CodeGroup>

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:

<Tabs>
  <Tab title="table (default in TTY)">
    ```bash theme={null} theme={null}
    asc apps list --output table
    ```

    Human-readable tabular output with borders.
  </Tab>

  <Tab title="json (default in pipes/CI)">
    ```bash theme={null} theme={null}
    asc apps list --output json
    ```

    Minified JSON for machine parsing.
  </Tab>

  <Tab title="json --pretty">
    ```bash theme={null} theme={null}
    asc apps list --output json --pretty
    ```

    Indented JSON for readability.
  </Tab>

  <Tab title="markdown">
    ```bash theme={null} theme={null}
    asc apps list --output markdown
    ```

    Markdown-formatted tables.
  </Tab>
</Tabs>

### Set a global default

```bash theme={null} theme={null}
export ASC_DEFAULT_OUTPUT=json
asc apps list  # Always outputs JSON
```

Explicit flags always override defaults:

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

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

### Parse JSON output with jq

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

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

```bash theme={null} theme={null}
asc builds list --app "123456789" --paginate
```

## Environment variables

Common environment variables for convenience:

```bash theme={null} theme={null}
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](/configuration/environment-variables) for the complete list.

## Next steps

<CardGroup cols={2}>
  <Card title="Command reference" icon="book" href="/commands/overview">
    Browse all available commands and flags
  </Card>

  <Card title="CI/CD integration" icon="gear" href="/cicd/overview">
    Automate workflows in GitHub Actions, GitLab CI, and more
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/configuration/workflows">
    Create multi-step automation with `asc workflow`
  </Card>

  <Card title="Guides" icon="book-open" href="/guides/automation">
    Real-world examples for common tasks
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found: asc">
    Ensure `asc` is in your `PATH`:

    ```bash theme={null} theme={null}
    which asc
    ```

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

    ```bash theme={null} theme={null}
    export PATH="$HOME/.local/bin:$PATH"
    ```
  </Accordion>

  <Accordion title="Authentication failed">
    Verify your credentials:

    ```bash theme={null} theme={null}
    asc auth status --validate
    ```

    Run the doctor to diagnose issues:

    ```bash theme={null} theme={null}
    asc auth doctor
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Network timeouts">
    Increase the timeout for slow connections:

    ```bash theme={null} theme={null}
    export ASC_TIMEOUT="120s"
    asc builds upload --app "123456789" --ipa large.ipa
    ```

    For uploads, use `ASC_UPLOAD_TIMEOUT`:

    ```bash theme={null} theme={null}
    export ASC_UPLOAD_TIMEOUT="300s"
    ```
  </Accordion>
</AccordionGroup>

## Get help

* **Built-in docs**: `asc --help` or `asc <command> --help`
* **GitHub Issues**: [Report bugs or request features](https://github.com/rorkai/App-Store-Connect-CLI/issues)
* **Discussions**: [Ask questions and share workflows](https://github.com/rorkai/App-Store-Connect-CLI/discussions)