gem-hunter
Language: Go
Fast, scriptable CLI for the App Store Connect API. Automate TestFlight, builds, submissions, signing, analytics, screenshots, subscriptions, and more
A fast, lightweight, and scriptable CLI for the App Store Connect API. Automate iOS, macOS, tvOS, and visionOS release workflows from your terminal, IDE, or CI/CD pipeline.
Agent Skills for automating asc workflows including builds, TestFlight, metadata sync, submissions, and signing:
https://github.com/rorkai/app-store-connect-cli-skills
Install them globally so they are available across projects:
asc install-skills
asc install-skills checks out reviewed commit
f52c4f04323bb2dfb21ca8be82e6494e9cd0b4d8 and copies its 25 skills directly
into the standard global agent-skills directory. It verifies the complete pack
and every installed file before succeeding, preserves unrelated skills and
unrelated lock entries, and pins the 25 ASC lock entries to the same reviewed
commit so external checks cannot update them from a mutable branch. It rolls
back the pack if any replacement fails. Only
git is required; the command does not execute Node.js, npx, an npm package,
or repository scripts.
git --version asc install-skills
If you want to confirm the binary works before configuring authentication:
asc version asc --help
# Homebrew (recommended) brew install asc # Install script (macOS/Linux) curl -fsSL https://asccli.sh/install | bash
# Windows (WinGet, once the package is accepted) winget install asc # Exact fallback when scripting winget install --id Rorkai.ASC --exact
The WinGet package is tracked in
GitHub Discussion #1552.
Until it appears in winget search asc, Windows users can download the
release binaries directly from the
GitHub releases page.
For source builds and contributor setup, see CONTRIBUTING.md.
Released binaries are self-contained and do not require a Go installation;
source builds use the toolchain version declared by go.mod.
Releases built with Go 1.27 require macOS 13 Ventura or later. On older Macs,
retain an older compatible release or upgrade macOS before updating asc.
asc auth login \ --name "MyApp" \ --key-id "ABC123" \ --issuer-id "DEF456" \ --private-key /path/to/AuthKey.p8 \ --network
Individual API keys have no issuer ID. Omit --issuer-id and pass --key-type individual:
asc auth login \ --name "MyIndividualKey" \ --key-id "ABC123" \ --key-type individual \ --private-key /path/to/AuthKey.p8
Generate API keys at: https://appstoreconnect.apple.com/access/integrations/api
If you are running in CI, a headless shell, or a machine where keychain access is not available, use config-backed auth instead:
asc auth login \ --bypass-keychain \ --name "MyCIKey" \ --key-id "ABC123" \ --issuer-id "DEF456" \ --private-key /path/to/AuthKey.p8
asc auth status --validate asc auth doctor
asc apps list --output table asc apps list --output json --pretty
asc chooses a default --output based on where stdout is connected:
tablejsonYou can still set a global preference:
export ASC_DEFAULT_OUTPUT=markdownAnd explicit flags always win:
asc apps list --output json
Commands are supported as documented. Deprecation warnings identify the available migration path and the command's long-term replacement.
brew update && brew upgrade ascwhich ascasc versionhttps://asccli.sh/installwinget source updatewinget install ascwinget install --id Rorkai.ASC --exactGet-Command asc and asc versionasc auth status --validateasc auth doctorASC_BYPASS_KEYCHAIN=1 or re-run asc auth login --bypass-keychainasc auth login --local --bypass-keychain ... when you want repo-local credentials in ./.asc/config.jsonasc system-statusasc system-status --service "App Store Connect"asc system-status --watch --poll-interval 30s--issues-only for a concise incident view; summary counts still cover all matched servicesasc defaults to table in an interactive terminal and json in pipes, files, and CI--output json, --output table, or --output markdown--pretty with JSON when you want readable output in terminals or bug reportsASC_DEFAULT_OUTPUT, but remember --output always winsasc sends pseudonymous command-level usage telemetry by default to help
maintainers understand which commands are used and where reliability work is
needed. Local events include a random installation ID, which lets events from
one installation be grouped over time; it is not derived from an Apple account
or machine identifier.
Telemetry includes the CLI version, operating system and architecture, registered command path, duration, runtime context, invocation source, a bounded outcome class, and the HTTP status when an API request fails. It may include a sanitized public flag name. It does not include raw arguments, stderr, error messages, flag values, response bodies, credentials, private keys, Apple account, team, or issuer IDs, app or bundle IDs, usernames, hostnames, repository names, or file paths.
Review or change telemetry at any time:
asc telemetry status asc telemetry disable asc telemetry reset-id
ASC_TELEMETRY_DISABLED=1 and DO_NOT_TRACK=1 also disable telemetry. See the
telemetry reference for the exact event payload,
runtime handling, collector endpoint, and all controls.
ASC_BYPASS_KEYCHAIN=1; if it is safe to do so, include redacted output from ASC_DEBUG=api asc ... or asc --api-debug ...Want to add yours?
asc apps wall submit --app "1234567890" --confirm
The command uses your authenticated gh session to fork the repo and open a pull request that updates docs/wall-of-apps.json.
It resolves the public App Store name, URL, and icon from the app ID automatically. For manual entries that are not on the public App Store yet, use --link with --name.
Use asc apps wall submit --dry-run to preview the fork, branch, and PR plan before creating anything.
asc testflight feedback list --app "123456789" --paginate asc testflight crashes list --app "123456789" --sort -createdDate --limit 10 asc testflight crashes log --submission-id "SUBMISSION_ID"
asc builds upload --app "123456789" --ipa "/path/to/MyApp.ipa" asc builds list --app "123456789" --output table asc testflight groups list --app "123456789" --output table
For macOS TestFlight distribution, upload the exported .pkg first, then add
the processed build to a beta group:
asc builds upload --app "123456789" --pkg "./build/MyMacApp.pkg" --version "1.2.3" --build-number "42" --wait --output json asc builds add-groups --app "123456789" --build-number "42" --version "1.2.3" --platform MAC_OS --group "Internal Testers"
--app is the App Store Connect app ID. If you use local Xcode build flags such
as --archive-path, also pass exactly one of --workspace or --project plus
--scheme; otherwise use a pre-exported .ipa or .pkg upload. Add
--submit --confirm to asc builds add-groups when distributing to an external
TestFlight group that needs beta app review submission.
# Optional: preview the staging plan before submission asc release stage --app "123456789" --version "1.2.3" --build-id "BUILD_ID" --copy-metadata-from "1.2.2" --dry-run # Canonical upload + attach + submit command asc publish appstore --app "123456789" --ipa "/path/to/MyApp.ipa" --version "1.2.3" --submit --confirm # Wait for the App Review decision (exit 0 approved, 1 rejected, 7 still pending at --timeout) asc status --app "123456789" --until review-done --timeout 2h
Lower-level submission lifecycle commands (for debugging or partial workflows):
# Canonical readiness check asc validate --app "123456789" --version "1.2.3" asc submit status --version-id "VERSION_ID" asc submit cancel --version-id "VERSION_ID" --confirm
Readiness validation also warns when localized app names, subtitles,
descriptions, keywords, promotional text, or What's New copy still contains an
unmistakable template marker such as Lorem ipsum, TODO, TBD, or FIXME.
Lorem ipsum matches in any letter case. TODO, TBD, and FIXME match only
in uppercase because their lowercase spellings can be ordinary product wording.
The same fields are checked for wording App Review commonly rejects:
content.other_platforms (Android, Google Play, other app stores) and
content.test_words (debug build, for testing purposes) are warnings, and
content.unfinished_features (coming soon, public beta, pre-release) is
informational because roadmap wording can be legitimate copy. Matching respects
word boundaries, so androids never matches, lowercase android is matched
only in keywords, and bare beta is ignored because it is ordinary wording in
health, audio, and finance apps. Each finding includes the locale, field,
matched text, resource ID, and a remediation step. Warnings are advisory by
default and become blocking only with --strict. A copyright year range that
ends before the current year is reported as
legal.format.copyright_year_outdated (info):
asc validate --app "123456789" --version "1.2.3" --output json asc validate --app "123456789" --version "1.2.3" --strict
Add the --deep mode when a release needs checks that Apple
exposes only through its signed-in web app:
asc web auth login --apple-id "user@example.com" asc validate --app "123456789" --version "1.2.3" --deep
Deep validation reuses the file-backed cache without opening a login, Keychain,
password, or 2FA prompt. It checks App Privacy publication, relevant agreements,
and the first auto-renewable subscription attachment; availability and required
App Review fields still come from the public API. Paid-agreement relevance also
uses the app's current public price so an upfront-paid app isn't mistaken for a
free one. The private Apple endpoints can change without notice, so an
unavailable or changed response is unverified, not a false blocker. Add
--strict if CI must fail when a requested deep check can't be verified.
Placeholder checks leave shorter Lorem Ipsum product wording and ordinary
localized TODO copy without marker punctuation unflagged; only template-like
residue is reported.
asc review status --app "123456789" asc review doctor --app "123456789"
asc localizations list --app "123456789" --type app-info asc metadata init --dir "./metadata" --version "1.2.3" --locale "en-US" # Fill in the values to apply and delete keys to leave unchanged; empty values are rejected. asc metadata apply --app "123456789" --version "1.2.3" --dir "./metadata" --dry-run asc metadata keywords audit --app "123456789" --version "1.2.3" --blocked-terms-file "./blocked-terms.txt" asc apps info view --app "123456789" --output json --pretty
Use asc metadata keywords audit before sync or apply when you want an ASO-focused
review of live keyword metadata across locales. It reports duplicate phrases, repeated
terms across locales, overlap with localized app name or subtitle, byte-budget usage,
and optional blocked terms from repeated --blocked-term flags or a text file.
asc screenshots plan --app "123456789" --version "1.2.3" --review-output-dir "./screenshots/review" asc screenshots apply --app "123456789" --version "1.2.3" --review-output-dir "./screenshots/review" --confirm asc screenshots list --version-localization "VERSION_LOCALIZATION_ID" asc video-previews list --version-localization "VERSION_LOCALIZATION_ID"
Uploading screenshots for a single locale:
asc apps list asc versions list --app "APP_ID" asc localizations list --version "VERSION_ID" --output json --locale "en-US" | jsonpp asc screenshots upload --version-localization "VERSION_LOCALIZATION_ID" --path "./screenshots/en-US" --device-type "IPHONE_65" --replace --confirm --max-screenshots 10
VERSION_LOCALIZATION_ID is the App Store version localization resource ID
from data[].id, not the locale code from attributes.locale.
For local capture coverage across multiple devices, locales, appearances, and content fixtures, use a matrix plan. Targets must already be booted simulators; the command writes raw artifacts and an offline review report, without uploading to App Store Connect:
asc screenshots matrix --plan .asc/screenshots-matrix.json --max-concurrency 2 --output json --pretty
See docs/design/screenshots-matrix.md for the JSONC schema, isolated output layout, retry behavior, and review contract.
asc bundle-ids capabilities list --bundle "BUNDLE_ID" asc signing fetch --bundle-id com.example.app --profile-type IOS_APP_STORE --output .asc/signing asc signing sync pull --repo git@github.com:team/signing.git --password-file ~/.config/asc/signing-sync-password --output-dir .asc/signing/pulled
signing fetch downloads public certificates and provisioning profiles. A
usable signing identity also needs the matching private key; signing sync
can verify that local identity and share it through an encrypted store (Git by
default). When the team has no active certificate, signing fetch --create-missing --create-missing-certificate creates the key, certificate,
profile, and .p12 in one pass. signing keychain installs and manages a
dedicated keychain, and xcode signing plan --profile maps downloaded profiles
onto Xcode targets; docs/CI_CD.md lists the fresh-runner
sequence. For multi-target release testing, signing reconcile plans exact
device/profile changes. signing run provides a temporary macOS keychain only
for single-target archives. Multi-target exports must import the identity into
a job-scoped keychain and install every reconciled profile for the job-exclusive
macOS user. See the
signing guide for setup, CI, rotation, security
boundaries, and troubleshooting.
asc workflow validate --output json asc workflow run --dry-run testflight_beta VERSION:1.2.3
asc api GET /v1/apps --query limit=5 asc api GET /v1/apps/APP_ID/relationships/builds --paginate asc api PATCH /v1/apps/APP_ID --confirm --body-file update.json
See docs/WORKFLOWS.md for local compile validation with
asc xcode build and a copyable .asc/deployment.json, .asc/workflow.json,
and ExportOptions.plist that use asc builds next-build-number,
asc xcode inject, asc xcode archive, asc xcode export --timeout 10m, and
asc publish testflight --group ... --wait.
Add --submit --confirm when
distributing to an external TestFlight group that needs beta app review submission.
The asc xcode test command provides local unit/UI test execution
with structured results and preserved .xcresult bundles; see the same workflow
guide for an invocation.
asc workflow validate --output json
asc xcode inject --manifest .asc/deployment.json --set version=1.2.3 --set build_number=42 --dry-run --output json
asc xcode build --project App.xcodeproj --scheme App --destination 'platform=iOS Simulator,name=iPhone 17 Pro Max,OS=27.0' --no-code-signing --output json
asc workflow run --dry-run testflight_beta VERSION:1.2.3
asc workflow run testflight_beta VERSION:1.2.3Replace the example Xcode destination with a simulator installed on the host.
# Trigger from a pull request asc xcode-cloud run --workflow-id "WORKFLOW_ID" --pull-request-id "PR_ID" # Rerun from an existing build run with a clean build asc xcode-cloud run --source-run-id "BUILD_RUN_ID" --clean # Fetch a single build run by ID asc xcode-cloud build-runs view --id "BUILD_RUN_ID"
Apple Ads uses separate OAuth credentials from App Store Connect:
asc ads auth login --name "Marketing" --client-id "SEARCHADS_CLIENT_ID" --team-id "SEARCHADS_TEAM_ID" --key-id "KEY_ID" --private-key ./ads-key.pem --ad-account "987654" asc ads auth discover --output json asc ads campaigns find --ad-account "987654" --file query.json --output json asc ads reports apps campaigns --ad-account "987654" --file report.json --output json
See guides/apple-ads-playbooks.mdx for operator playbooks covering credential safety, org inspection, read-only smoke tests, reporting, raw API usage, and guarded mutations.
The App Store Server API and Retention Messaging use a dedicated In-App Purchase API key, separate from App Store Connect API credentials:
asc storekit auth login --name Production --key-id "KEY_ID" --issuer-id "ISSUER_ID" --private-key ./SubscriptionKey.p8 --bundle-id com.example.app asc storekit auth doctor --environment sandbox --network asc storekit transactions history --transaction-id "2000000000000001" --environment production --paginate asc storekit subscriptions status --transaction-id "2000000000000001" --environment production --output table asc storekit notifications history --start 2026-09-01 --end 2026-09-08 --only-failures --environment production asc storekit retention-messaging messages list --environment sandbox --output json
JSON output prints Apple's response unmodified. --decode adds decoded JWS
payloads without verifying Apple's signature, so don't grant entitlements from
decoded output alone.
See docs/architecture/storekit-retention-messaging.md for the endpoint map, message and image requirements, environment variables, and the full sandbox verification sequence.
Use built-in help as the source of truth:
asc --help asc <command> --help asc <command> <subcommand> --help
Reference hierarchy:
asc --help: authoritative command and flag surfacedocs/COMMANDS.md: generated top-level taxonomy mapasc docs show workflows: curated workflow recipesasc docs show reference: repo-local quick reference template used by asc initFor full command families, flags, and discovery patterns, see:
Local screenshot framing uses Koubou (pinned to 0.20.0) for deterministic device-frame rendering.
GitHub: https://github.com/bitomule/koubou
Simulator UI automation for screenshot capture and interactions uses AXe CLI. GitHub: https://github.com/cameroncooke/AXe
The keyword difficulty methodology used by asc optimize keywords score is adapted from semihcihan's App Store Optimization CLI (MIT licensed).
GitHub: https://github.com/semihcihan/App-Store-Optimization-CLI
For portable Linux iOS builds and local IPA packaging with xtool and rcodesign, see the Linux iOS workflow. Native simulator execution still requires a Mac host; existing Xcode archive/export helpers retain their contracts.
Contributions are welcome. See CONTRIBUTING.md for details.
MIT License - see LICENSE for details.
This project is an independent, unofficial tool and is not affiliated with, endorsed by, or sponsored by Apple Inc. App Store Connect, TestFlight, Xcode Cloud, and Apple are trademarks of Apple Inc., registered in the U.S. and other countries.