Frequently Asked Questions

Common questions about the App Store Connect CLI

What is the App Store Connect CLI?

The App Store Connect CLI (asc) is an unofficial, fast, lightweight, and scriptable command-line tool for the App Store Connect API. It allows you to automate iOS, macOS, tvOS, and visionOS release workflows from your terminal, IDE, or CI/CD pipeline.Built in Go using ffcli, it provides a comprehensive interface to manage apps, builds, TestFlight, reviews, analytics, signing, and more.

Is this an official Apple tool?

No. This is an independent, unofficial tool and is not affiliated with, endorsed by, or sponsored by Apple Inc. It uses the public App Store Connect API that Apple provides for developers.App Store Connect, TestFlight, Xcode Cloud, and Apple are trademarks of Apple Inc., registered in the U.S. and other countries.

How do I install the CLI?

The recommended installation method is via Homebrew:

brew install asc

Alternatively, use the install script:

curl -fsSL https://asccli.sh/install | bash

For source builds and contributor setup, see the Contributing Guide.

How do I authenticate with App Store Connect?

You need an App Store Connect API key. Generate one at: https://appstoreconnect.apple.com/access/integrations/apiThen authenticate using:

asc auth login \
  --name "MyApp" \
  --key-id "ABC123" \
  --issuer-id "DEF456" \
  --private-key /path/to/AuthKey.p8

Credentials are stored securely in the system keychain (macOS) or config file (~/.asc/config.json) with restricted permissions.

Can I use environment variables for authentication?

Yes. The CLI supports multiple authentication methods:

export ASC_KEY_ID="YOUR_KEY_ID"
export ASC_ISSUER_ID="YOUR_ISSUER_ID"
export ASC_PRIVATE_KEY_PATH="/path/to/AuthKey.p8"

# Or use base64-encoded key for CI/CD
export ASC_PRIVATE_KEY_B64="BASE64_ENCODED_KEY"

To bypass keychain entirely:

export ASC_BYPASS_KEYCHAIN=1

Priority order: Environment variables > Config file > Keychain

What permissions does my API key need?

Permissions depend on what operations you want to perform:

App Manager: Most operations (builds, TestFlight, metadata, screenshots)
Admin: Full access including user management
Developer: Read-only access to most resources
Sales: Access to sales and analytics reports
Finance: Access to financial reports
Customer Support: Access to customer reviews and feedback

Generate keys with the minimum required permissions for your use case.

How do I list all available commands?

Use the built-in help system:

asc --help                    # List all commands
asc builds --help             # List builds subcommands
asc builds list --help        # Show all flags for a specific command

The CLI is self-documenting. Always check --help for the current interface before running commands.

What output formats are supported?

The CLI supports multiple output formats:

json - Machine-readable JSON
table - Human-readable table (default in terminals)
markdown or md - Markdown tables

Output defaults are TTY-aware:

Interactive terminal: table
Pipes/files/CI: json

Set a global default:

export ASC_DEFAULT_OUTPUT=json

Or use explicit flags (always takes precedence):

asc apps list --output json

How do I handle pagination?

Use the --paginate flag to automatically fetch all pages:

asc testflight feedback list --app "123456789" --paginate
asc analytics view --request-id "REQUEST_ID" --date "2024-01-01" --paginate

Without --paginate, only the first page (default limit) is returned. This is especially important for:

Analytics reports with large datasets
Complete feedback/crash lists
Comprehensive build history

Can I use this in CI/CD pipelines?

Yes! The CLI is designed for automation and supports:

GitHub Actions: Use the official setup-asc action
GitLab CI/CD: Use asc-ci-components
Bitrise: Use the setup-asc step
CircleCI: Use the asc orb

See the CI/CD guide for detailed examples.

How do I upload builds to TestFlight?

Upload IPA or PKG files using:

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

For large files, increase timeout:

export ASC_UPLOAD_TIMEOUT=10m
asc builds upload --app "123456789" --ipa "/path/to/large.ipa"

Then check processing status:

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

How do I get TestFlight feedback and crash reports?

Fetch feedback:

asc testflight feedback list --app "123456789" --paginate --output json

Fetch recent crashes:

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

For detailed crash information, filter by build:

asc testflight crashes list --app "123456789" --build "BUILD_ID"

Can I manage app metadata and localizations?

Yes. View app information:

asc apps info view --app "123456789" --output json --pretty

List localizations:

asc localizations list --app "123456789"

Update metadata using PATCH operations:

asc app-setup info set --app "123456789" --locale en-US --name "New App Name"

How do I work with signing certificates and profiles?

List certificates:

asc certificates list

List provisioning profiles:

asc profiles list

List bundle IDs:

asc bundle-ids list

Create new resources or revoke existing ones using the respective create and delete subcommands.

What are workflows and how do I use them?

Workflows allow you to automate complex multi-step processes. Define workflows in JSON:

{
  "workflows": {
    "release": {
      "steps": [
        {"command": "validate", "args": ["--app", "123456789"]},
        {"command": "submit", "args": ["--app", "123456789"]}
      ]
    }
  }
}

Run the workflow:

asc workflow run --file .asc/workflow.json release

How do I enable debug logging?

Enable debug mode to see detailed HTTP request/response logs:

export ASC_DEBUG=api
asc apps list

This shows:

Request URLs and headers
Response status codes and bodies
Retry attempts and timing

Useful for troubleshooting API issues or reporting bugs.

How do I handle API rate limits?

The CLI automatically retries GET/HEAD requests on 429/503 responses. Configure retry behavior:

export ASC_MAX_RETRIES=5
export ASC_BASE_DELAY=1s
export ASC_MAX_DELAY=30s
export ASC_RETRY_LOG=true

Note: POST/PATCH/DELETE requests are NOT automatically retried to prevent duplicate operations.For long-running operations, increase timeouts:

export ASC_TIMEOUT=2m

What's the difference between sales and finance reports?

Sales reports: Daily/weekly/monthly sales data, units sold, proceeds
Finance reports: Apple fiscal month reports, payments, regions

Sales reports use calendar dates:

asc analytics sales --vendor "12345678" --type SALES --subtype SUMMARY --frequency DAILY --date "2024-01-15"

Finance reports use Apple fiscal months (YYYY-MM):

asc finance reports --vendor "12345678" --report-type FINANCIAL --region ZZ --date "2024-01"

See API Notes for detailed quirks.

Can I manage sandbox testers?

Yes. List sandbox testers:

asc sandbox list

View a specific tester:

asc sandbox view --email "[email protected]"

Update an existing tester:

asc sandbox update --id "SANDBOX_TESTER_ID" --territory USA

The current CLI supports list, view, update, and clear-history for sandbox testers. Territory uses 3-letter codes such as USA and JPN.

How do I work with Game Center?

Game Center operations require a Game Center detail ID. First, check if Game Center is enabled:

asc game-center details list --app "123456789"

Then manage achievements, leaderboards, and releases. Note:

Releases are required to make resources live
Image uploads follow a three-step flow (reserve → upload → commit)
Some relationships are replace-only (PATCH)

See API Notes for Game Center quirks.

Where can I find API documentation?

Prefer the sosumi.ai mirror over developer.apple.com:Replace:

https://developer.apple.com/documentation/appstoreconnectapi/...

With:

https://sosumi.ai/documentation/appstoreconnectapi/...

For offline reference, check the OpenAPI snapshot:

docs/openapi/latest.json
docs/openapi/paths.txt

How do I contribute to the project?

Contributions are welcome! See the Contributing Guide for:

Development setup
Testing requirements
PR guidelines
Local validation checklist

All PRs must pass formatting, linting, and tests:

make format
make lint
ASC_BYPASS_KEYCHAIN=1 make test

How do I report security issues?

Do NOT open public GitHub issues for security vulnerabilities.Report privately using GitHub Security Advisories: https://github.com/rorkai/App-Store-Connect-CLI/security/advisories/newInclude:

Clear vulnerability description and impact
Steps to reproduce
Affected versions and platforms

What is asc skills?

asc skills are agent-based automation workflows for common CLI operations including:

Build uploads and distribution
TestFlight management
Metadata synchronization
App submissions
Signing and provisioning

Learn more: https://github.com/rorkai/app-store-connect-cli-skills

Can I use this on Linux?

Yes! The CLI supports both macOS and Linux.On Linux:

Keychain features fall back to config file storage
Ensure Go 1.26+ is installed
All core functionality works identically

Install using the install script:

curl -fsSL https://asccli.sh/install | bash

How do I update to the latest version?

If installed via Homebrew:

brew upgrade asc

If installed via install script, re-run:

curl -fsSL https://asccli.sh/install | bash

Check current version:

asc version

View releases: https://github.com/rorkai/App-Store-Connect-CLI/releases

Why does output format change between terminal and scripts?

The CLI is TTY-aware and adapts output based on context:

Interactive terminal (TTY): Defaults to table for readability
Pipes/files/CI (non-TTY): Defaults to json for machine parsing

This ensures:

Human-friendly output when exploring interactively
Machine-parseable output in automation

Override with --output flag or ASC_DEFAULT_OUTPUT environment variable.

Where can I get help?

Multiple resources are available:

Built-in help: asc --help and asc <command> --help
Documentation: Full command reference and guides
GitHub Issues: Report bugs or request features
Troubleshooting: See Troubleshooting Guide
API Notes: Check API Notes for quirks

For issues: https://github.com/rorkai/App-Store-Connect-CLI/issues

Resources

Faq

Frequently Asked Questions

​Frequently Asked Questions

Frequently Asked Questions