App Store Connect Upload Tool

简体中文 | Tutorials

asc is a Python 3.9+ CLI for routine App Store Connect release work. Use it from the terminal or its local Web UI to manage localized store content, in-app purchases, Xcode builds, and releases across multiple apps.

What You Can Do

• Upload localized metadata, keywords, store URLs, and screenshots
• Create or update in-app purchases and auto-renewable subscriptions from JSON
• Upload missing IAP and subscription review screenshots
• Update What's New text, with optional LLM-assisted translation
• Build Xcode projects, export .ipa files, and upload builds to App Store Connect for TestFlight or App Store distribution
• Manage multiple App Profiles with project-local defaults
• Run common workflows from a local Web UI with persistent task history and Webhook notifications
• Protect state-changing operations with machine, network, and credential Guard checks

Requirements

• Python 3.9 or later
• An App Store Connect API key with the App Manager role or higher
• The key's Issuer ID, Key ID, .p8 private key, and the app's numeric Apple ID
• macOS with Xcode command line tools for build, deploy, and release

Metadata, screenshot, IAP, and Web UI workflows can run on Linux and Windows. Apple allows each .p8 private key to be downloaded only once, so store it securely.

Quick Start

1. Install asc

Preferred: install the published package from PyPI.

python -m pip install asc-appstore-tools

On macOS / Linux, the repository installer also defaults to PyPI (GitHub is a fallback, or use --ref for a branch):

curl -fL --retry 5 --connect-timeout 20 \
  -o /tmp/asc-install.sh \
  https://raw.githubusercontent.com/yinghuiwang/AppStoreTools/main/install.sh
bash /tmp/asc-install.sh

Alternatively, install the published package or the latest source:

python -m pip install asc-appstore-tools
# or
python -m pip install git+https://github.com/yinghuiwang/AppStoreTools.git

2. Configure a project

Run the guided setup from your Xcode project. It checks the environment and helps create or import an App Profile:

cd /path/to/MyXcodeProject
asc install

For manual setup, use asc init to scaffold AppStore/ data or asc app add myapp to create a profile. Profiles and copied private keys are stored outside the project under ~/.config/asc/.

3. Check and preview

Verify credentials and preview the default metadata and screenshot upload before changing App Store Connect:

asc check
asc upload --dry-run

Use asc --app myapp <command> to select a profile explicitly, or set one once with asc app default myapp.

Common Workflows

Metadata and screenshots

# An imported asc init profile points to AppStore/data/appstore_info.csv
asc metadata --dry-run

# The same profile points to AppStore/data/screenshots/
asc screenshots --dry-run

See Metadata & Screenshots for the CSV columns, locale folders, supported display types, and upload behavior.

IAP and subscriptions

asc iap --iap-file AppStore/data/iap_packages.json --dry-run
asc iap --iap-file AppStore/data/iap_packages.json --update-existing

# Find products missing a review image and upload configured defaults
asc iap-screenshots --iap-file AppStore/data/iap_packages.json --dry-run

Start from the current template generated by asc init at AppStore/data/iap_packages.json. A repository checkout also contains sample data at data/iap_packages.json. See IAP & Subscriptions for the schema and update rules.

What's New and store URLs

asc whats-new --text "Bug fixes and performance improvements." --dry-run

# Translate one source text to the app's other locales through an OpenAI-compatible API
asc whats-new --text "Bug fixes and performance improvements." \
  --translate --source-locale en-US --dry-run

asc set-support-url --text "https://example.com/support" --dry-run
asc set-marketing-url --text "https://example.com" --dry-run
asc set-privacy-policy-url --text "https://example.com/privacy" --dry-run

LLM settings are managed from the Web UI or ~/.config/asc/llm.toml; OPENAI_API_KEY is also supported. File-based release notes and locale selection are covered in What's New & Store URLs.

Build and release

asc build --dry-run
asc --app myapp deploy --ipa build/export/MyApp.ipa --dry-run
asc --app myapp release --destination testflight --dry-run

asc build and asc release can discover the Xcode project, scheme, bundle ID, signing certificate, and provisioning profile, then cache resolved values in .asc/config.toml. See Build & Deploy for signing and App Store release options.

Local Web UI

asc web
asc web status
asc web stop

Production asc web serves the Vue 3 SPA at http://127.0.0.1:8080 by default. It exposes the main upload and release workflows, keeps task history in ~/.config/asc/tasks.db, and can send completion notifications to Feishu, WeCom, or DingTalk from its settings page.

Local development uses two processes (do not add asc web --vite):

asc web --foreground
cd frontend && npm run dev

Vite on :5173 proxies /api and /static to the FastAPI app. A release build requires npm ci && npm run build first so src/asc/web/static/spa/ is included in the package.

Run asc --help for all commands and asc <command> --help for every option.

Configuration

Values are resolved in this order, from highest to lowest priority:

1. CLI options such as --app, --csv, or --screenshots
2. Project-local .asc/config.toml
3. Global App Profile
4. Environment variables

Location	Purpose
.asc/config.toml	Project defaults, including the default app and build settings
.asc/error.log	Detailed errors for commands run from the current project
~/.config/asc/profiles/	Reusable App Profiles and App Store Connect credentials
~/.config/asc/keys/	Private keys copied during profile setup
~/.config/asc/llm.toml	OpenAI-compatible translation providers
~/.config/asc/webhook.toml	Web task notification settings
~/.config/asc/tasks.db	Persistent Web UI task history and logs

For multiple apps, profile import, default selection, and CI environment variables, see Multi-App Profiles and CI/CD Automation.

Tutorials

#	Guide	Covers
01	Install & Project Init	Installation, API keys, project templates, and the first profile
02	Metadata & Screenshots	CSV content, screenshot folders, validation, and uploads
03	IAP & Subscriptions	JSON schema, one-time purchases, and subscriptions
04	What's New & Store URLs	Release notes and support, marketing, and privacy URLs
05	Build & Deploy	Archives, signing, IPA export, and uploads for TestFlight or App Store distribution
06	Multi-App Profiles	Profile management and project defaults
07	Guard Security	Machine, network, and credential binding
08	CI/CD Automation	Non-interactive setup and GitHub Actions

Development

git clone https://github.com/yinghuiwang/AppStoreTools.git
cd AppStoreTools
python -m pip install -e ".[dev]"
pytest
python -m build

Browser E2E (tests/test_web_agent_e2e.py) needs Playwright Chromium and is skipped if the browser is missing:

python -m playwright install chromium
pytest tests/test_web_agent_e2e.py

Source code lives in src/asc/; tests mirror the feature areas under tests/. Publishing is handled by .github/workflows/publish.yml when a v*.*.* tag is pushed.

After changing the Vue UI, rebuild production assets with cd frontend && npm ci && npm run build (requires Node). Fonts stay under src/asc/web/static/.

Security

• Never commit .p8 keys, .env files, local profiles, or generated credentials.
• Use --dry-run before metadata, screenshot, IAP, URL, build, or release changes.
• Keep Guard enabled on developer machines; use asc guard status to inspect bindings.
• Bind the Web UI to 127.0.0.1 unless access from another machine is intentional.
• Keep API keys and Webhook secrets in environment variables or the configuration files under ~/.config/asc/, not in upload data.

Troubleshooting

asc: command not found

Open a new terminal or reload the shell configuration:

source ~/.zshrc
# or
source ~/.bash_profile

asc check reports no editable version

Create an App Store version in App Store Connect first. The version must be in an editable state such as PREPARE_FOR_SUBMISSION.

A Guard check blocks an operation

Run asc guard status to see the active binding and conflict. Follow Guard Security before unbinding or disabling protection.

A command fails without enough detail

Re-run it with the global debug option, for example asc --debug upload --dry-run, and inspect .asc/error.log.