ascelerate
A command-line tool for building, archiving, and publishing apps to the App Store — from Xcode archive to App Review submission. Built with Swift on the App Store Connect API.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/keremerkan/ascelerate with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/keremerkan/ascelerate'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/keremerkan--ascelerate)HTML
<a href="/listings/keremerkan--ascelerate"><img src="/api/listings/keremerkan--ascelerate/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
Homebrew
brew tap keremerkan/tap brew trust keremerkan/tap brew install ascelerate
Since Homebrew 6.0, third-party taps must be explicitly trusted before their code runs. The `brew trust` step above approves the tap; alternatively, a fully-qualified install (`brew install keremerkan/tap/ascelerate`) prompts you to trust it interactively.
The tap provides a pre-built binary for Apple Silicon Macs, so installation is instant.
Install script
curl -sSL https://raw.githubusercontent.com/keremerkan/ascelerate/main/install.sh | bash
Downloads the latest release, installs to `/usr/local/bin`, and removes the quarantine attribute automatically. Apple Silicon only.
Download manually
Download the latest release from [GitHub Releases](https://github.com/keremerkan/ascelerate/releases):
curl -L https://github.com/keremerkan/ascelerate/releases/latest/download/ascelerate-macos-arm64.tar.gz -o ascelerate.tar.gz tar xzf ascelerate.tar.gz mv ascelerate /usr/local/bin/
Since the binary is not signed or notarized, macOS will quarantine it on first download. Remove the quarantine attribute:
xattr -d com.apple.quarantine /usr/local/bin/ascelerate
> **Note:** Pre-built binaries are provided for Apple Silicon (arm64) only. Intel Mac users should build from source.
Build from source
git clone https://github.com/keremerkan/ascelerate.git cd ascelerate swift build -c release strip .build/release/ascelerate cp .build/release/ascelerate /usr/local/bin/
> **Note:** The release build takes a few minutes because the [asc-swift](https://github.com/aaronsky/asc-swift) dependency includes ~2500 generated source files covering the entire App Store Connect API surface. `strip` removes debug symbols, reducing the binary from ~175 MB to ~59 MB.
Shell completions
Set up tab completion for subcommands, options, and flags (supports zsh and bash):
ascelerate install-completions
This detects your shell and configures everything automatically. Restart your shell or open a new tab to activate.
AI coding skill
ascelerate ships with a skill file that gives AI coding agents (Claude Code, Grok Build, Cursor, Windsurf, GitHub Copilot) full knowledge of all commands, JSON formats, and workflows.
**Via the binary** (detects your installed agents):
ascelerate install-skill # install/update for every detected agent ascelerate install-skill --all # include all supported agents (e.g. Copilot)
It auto-detects Claude Code, Grok Build (which reads the Claude Code skill path natively), Cursor, and Windsurf (and GitHub Copilot with `--all`), installs/updates the skill for each, and checks for outdated skills on each run to prompt you after upgrades.
**Via npx** (any AI coding agent):
npx ascelerate-skill
This presents an interactive menu to select your agent and installs the skill to the appropriate directory. The skill file is fetched from GitHub, so it's always up to date. Use `npx ascelerate-skill --uninstall` to remove it.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 1,645 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- <p align="center">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="website/static/img/icon-dark.png">
- <img src="website/static/img/icon.png" width="128" alt="ascelerate icon">
- </picture>
- </p>
- # ascelerate — A Swift CLI for App Store Connect
- A command-line tool for building, archiving, and publishing apps to the App Store — from Xcode archive to App Review submission. Built with Swift on the [App Store Connect API](https://developer.apple.com/documentation/appstoreconnectapi).
- > **Note:** Covers the core app release workflow: archiving, uploading builds, managing versions and localizations, screenshots, review submission, provisioning (devices, certificates, bundle IDs, profiles), and full management of in-app purchases and subscriptions. Also handles customer reviews and developer responses, in-app events, custom product pages, and Sales/Finance/Analytics report downloads. Most provisioning commands support interactive mode — run without arguments to get guided prompts.
- > **Full documentation:** [ascelerate.dev](https://ascelerate.dev)
- > **Prefer an app?** Ascelerate brings App Store Connect to Mac, iPhone and iPad, built on ascelerate. See [Ascelerate: the app](#ascelerate-the-app).
- ## Ascelerate: the app
- [Ascelerate](https://ascelerate.app) is App Store Connect as a native app for Mac, iPhone and iPad, built on ascelerate's App Store Connect client. It's in beta: [join on TestFlight](https://testflight.apple.com/join/K4Yvdfqh). Coming soon to the App Store, for macOS 27 and iOS and iPadOS 27 or later.
- - **Versions and product pages:** descriptions, what's new, keywords, screenshots and app previews in every language, with a check of what App Review needs before you submit.
- - **TestFlight:** builds, groups and testers, What to Test, beta review and tester feedback.
- - **In-app purchases and subscriptions:** prices in every territory, introductory and promotional offers, offer codes and promoted purchases.
- - **Growth:** in-app events, custom product pages, product page optimization tests, featuring nominations, and ratings and reviews with your responses.
- - **Certificates, Identifiers & Profiles:** certificates, bundle IDs and their capabilities, devices and provisioning profiles.
- - **Reports:** Sales and Trends and App Analytics, and an overview of what needs your attention across your apps.
- - **Apple Ads:** campaigns, ad groups, keywords and their performance.
- - **On iPhone and iPad:** keep up with your apps wherever you are, and have your Mac archive and send a build while you're away.
- Archiving and uploading builds and capturing screenshots run Xcode and the simulators, which a Mac App Store app can't do on its own. The free [Ascelerate Helper](https://ascelerate.app/helper) installs ascelerate for the Mac app to run them.
- ## Requirements
- - macOS 15+
- - Swift 6.2+ (only for building from source)
- ## Installation
- ### Homebrew
- ```bash
- brew install ascelerate
- ```
- Homebrew installs a pre-built binary on Apple silicon Macs and builds from source on Intel Macs. If you installed ascelerate from the `keremerkan/tap` tap before, `brew update` moves it to Homebrew's own formula.
- ### Install script
- ```bash
- curl -fsSL https://raw.githubusercontent.com/keremerkan/ascelerate/main/install.sh | bash
- ```
- Downloads the latest release, checks that it's signed with ascelerate's Developer ID, and installs it to `/usr/local/bin` (creating the folder if needed), which asks for your password. Apple Silicon only. Update it later with `sudo ascelerate update`.
- ### Download manually
- Download the latest release from [GitHub Releases](https://github.com/keremerkan/ascelerate/releases):
- ```bash
- curl -L https://github.com/keremerkan/ascelerate/releases/latest/download/ascelerate-macos-arm64.tar.gz -o ascelerate.tar.gz
- tar xzf ascelerate.tar.gz
- sudo mkdir -p /usr/local/bin
- sudo mv ascelerate /usr/local/bin/
- ```
- The binary is signed with ascelerate's Developer ID (AKE Software GmbH) and notarized by Apple, so macOS runs it without a warning. `codesign -dv /usr/local/bin/ascelerate` shows the signature; `sudo ascelerate update` installs later releases.
- > **Note:** Pre-built binaries are provided for Apple Silicon (arm64) only. Intel Mac users should build from source.
- ### Build from source
- ```bash
- git clone https://github.com/keremerkan/ascelerate.git
- cd ascelerate
- swift build -c release
- strip .build/release/ascelerate
- cp .build/release/ascelerate /usr/local/bin/
- ```
- > **Note:** The release build takes several minutes because it compiles the App Store Connect client that ascelerate generates from Apple's OpenAPI specification. `strip` removes debug symbols, reducing the binary from ~156 MB to ~41 MB.
- ### Shell completions
- Set up tab completion for subcommands, options, and flags (supports zsh and bash):
- ```bash
- ascelerate install-completions
- ```
- This detects your shell and configures everything automatically. Restart your shell or open a new tab to activate.
- ### AI coding skill
- ascelerate ships with a skill file that gives AI coding agents (Claude Code, Grok Build, Cursor, Windsurf, GitHub Copilot) full knowledge of all commands, JSON formats, and workflows.
- **Via the binary** (detects your installed agents):
- ```bash
- ascelerate install-skill # install/update for every detected agent
- ascelerate install-skill --all # include all supported agents (e.g. Copilot)
- ```
- It auto-detects Claude Code, Grok Build (which reads the Claude Code skill path natively), Cursor, and Windsurf (and GitHub Copilot with `--all`), installs/updates the skill for each, and checks for outdated skills on each run to prompt you after upgrades.
- **Via npx** (any AI coding agent):
- ```bash
- npx ascelerate-skill
- ```
- This presents an interactive menu to select your agent and installs the skill to the appropriate directory. The skill file is fetched from GitHub, so it's always up to date. Use `npx ascelerate-skill --uninstall` to remove it.
- ## Setup
- ### 1. Create an API Key
- Go to [App Store Connect > Users and Access > Integrations > App Store Connect API](https://appstoreconnect.apple.com/access/integrations/api) and generate a new key. Download the `.p8` private key file.
- ### 2. Configure
- ```bash
- ascelerate configure
- ```
- This will prompt for your **Key ID**, **Issuer ID**, and the path to your `.p8` file, plus an optional **vendor number** (only needed for `reports sales`/`reports finance`). The private key is copied into `~/.ascelerate/` with strict file permissions (owner-only access).
- ### A key for one run
- To run a command with another key, for another team or in CI, set all three environment variables. They take precedence over `config.json` for that run, and the file stays as it is:
- ```bash
- export ASCELERATE_KEY_ID=KEY_ID
- export ASCELERATE_ISSUER_ID=ISSUER_ID
- export ASCELERATE_PRIVATE_KEY_PATH=~/keys/AuthKey_KEY_ID.p8
- ascelerate apps list
- ```
- `builds archive` and `builds upload` also hand this key to `xcodebuild` (`-authenticationKeyPath`, `-authenticationKeyID`, `-authenticationKeyIssuerID`), so profiles are fetched with the key instead of the Apple ID signed in to Xcode. That needs a key allowed to manage certificates, identifiers and profiles. `ascelerate configure --show` says which key a run uses.
- ## Usage
- ### Aliases
- Instead of typing full bundle IDs every time, you can create short aliases:
- ```bash
- # Add an alias (interactive app picker)
- ascelerate alias add myapp
- # Now use the alias anywhere you'd use a bundle ID
- ascelerate apps info myapp
- ascelerate apps versions myapp
- ascelerate apps localizations view myapp
- # List all aliases
- ascelerate alias list
- # Remove an alias
- ascelerate alias remove myapp
- ```
- Aliases are stored in `~/.ascelerate/aliases.json`. Any argument that doesn't contain a dot is looked up as an alias — real bundle IDs (which always contain dots) work unchanged.
- ### JSON output
- Read commands support `--json` for machine-readable output, ready for `jq`, scripts, and AI agents:
- ```bash
- ascelerate apps list --json
- ascelerate apps info <bundle-id> --json
- ascelerate apps versions <bundle-id> --json
- ascelerate apps review preflight <bundle-id> --json
- ascelerate apps review status <bundle-id> --json
- ascelerate builds list --bundle-id <bundle-id> --json
- ascelerate testflight builds <bundle-id> --json
- ascelerate testflight status <bundle-id> --json
- ascelerate reviews list <bundle-id> --json
- ascelerate reviews info <review-id> --json
- ascelerate iap list <bundle-id> --json
- ascelerate iap info <bundle-id> <product-id> --json
- ascelerate iap pricing show <bundle-id> <product-id> --json
- ascelerate sub groups <bundle-id> --json
- ascelerate sub list <bundle-id> --json
- ascelerate sub info <bundle-id> <product-id> --json
- ascelerate sub pricing show <bundle-id> <product-id> --json
- ascelerate rate-limit --json
- ```
- List commands emit a top-level JSON array, detail commands a single object. Enum values are raw API constants (`WAITING_FOR_REVIEW`, `IOS`), dates are ISO 8601, every resource carries its `id`, null fields are omitted, and empty results emit `[]` — never prose. Warnings become booleans (`iap info`/`sub info` report `"hasPricing": false`). `--json` implies non-interactive mode, and errors go to stderr so stdout is always valid JSON.
- ### Apps
- ```bash
- # List all apps
- ascelerate apps list
- # Show app details
- ascelerate apps info <bundle-id>
- # List App Store versions
- ascelerate apps versions <bundle-id>
- # Create a new version
- ascelerate apps create-version <bundle-id> <version-string>
- ascelerate apps create-version <bundle-id> 2.1.0 --platform ios --release-type manual
- # View or update the copyright notice
- ascelerate apps copyright <bundle-id>
- ascelerate apps copyright <bundle-id> --set "2026 Your Name" --version 2.1.0 --platform macos
- # Check review submission status
- ascelerate apps review status <bundle-id>
- ascelerate apps review status <bundle-id> --version 2.1.0
- # Submit for review
- ascelerate apps review submit <bundle-id>
- ascelerate apps review submit <bundle-id> --version 2.1.0
- ascelerate apps review submit <bundle-id> --platform macos
- # Resolve rejected review items (after fixing issues and replying in Resolution Center)
- ascelerate apps review resolve-issues <bundle-id>
- # Cancel an active review submission
- ascelerate apps review cancel-submission <bundle-id>
- # View or update App Review Information (contact, demo account, notes)
- ascelerate apps review info <bundle-id>
- ascelerate apps review info <bundle-id> --contact-email you@example.com --demo-account-name reviewer --demo-account-password "hunter2" --demo-account-required true --notes "Steps to test…"
- # App Review attachment files (demo videos, docs, etc.)
- ascelerate apps review attachment list <bundle-id>
- ascelerate apps review attachment upload <bundle-id> demo.mp4
- ascelerate apps review attachment delete <attachment-id>
- ```
- For universal-purchase apps (one App Store record spanning iOS, macOS, tvOS, and/or visionOS), the same version string can exist once per platform. `create-version` and `review submit` default to iOS — pass `--platform macos` (or `tvos`, `visionos`) to target another platform. All other version-scoped commands (localizations, media, build attach, review preflight/info/attachments/resolve-issues/cancel-submission, phased release, release, routing coverage) accept an optional `--platform` as well; without it they prompt whenever a version (or active review submission) matches more than one platform — and refuse with a hint instead of prompting under `--yes`.
- #### Pre-submission preflight checks
- Before submitting for review, run `preflight` to verify that all required fields are filled in across every locale:
- ```bash
- # Check the latest editable version
- ascelerate apps review preflight <bundle-id>
- # Check a specific version
- ascelerate apps review preflight <bundle-id> --version 2.1.0
- ```
- The command checks the version's state and build (processed, with export compliance answered), its copyright, App Review contact and sign-in, and the app's primary category, content rights, price and availability. Then it goes through each language: app info (name, and the privacy policy URL in the primary language), the version's text (description and keywords in every language, the support URL in the primary language) and screenshots. A language without screenshots of its own shows the primary language's on the App Store, so only the primary language needs them. Results are grouped by locale with colored pass/fail indicators:
- ```
- Preflight checks for MyApp v2.1.0 (Prepare for Submission)
- Check Status
- ──────────────────────────────────────────────────────────────────
- Version state ✓ Prepare for Submission
- Build attached ✓ Build 42
- Copyright ✓ 2026 Your Name
- Review contact ✓ Jane Doe, jane@example.com
- Sign-in ✓ Not required
- Category ✓ Productivity
- Content rights ✓ Does Not Use Third Party Content
- Price ✓ Set
- Availability ✓ 175 territories
- en-US (English (United States))
- App info ✓ All fields filled
- Localizations ✓ All fields filled
- Screenshots ✓ 2 sets, 10 screenshots
- de-DE (German (Germany))
- App info ✓ All fields filled
- Localizations ✗ Missing: Keywords, What's New
- Screenshots ✓ None (uses en-US's)
- ──────────────────────────────────────────────────────────────────
- Result: 14 passed, 1 failed
- ```
- What's New is checked only for updates: once a version of the same platform has been released. A release on another platform doesn't count, so the first Mac version of an iOS app needs none.
- Exits with a non-zero status when any check fails, making it suitable for CI pipelines and workflow files. With `--json`, it emits a structured report — a `passed` boolean plus one entry per check — while keeping the same exit-code behavior.
- ### Build Management
- ```bash
- # Interactively select and attach a build to a version
- ascelerate apps build attach <bundle-id>
- ascelerate apps build attach <bundle-id> --version 2.1.0
- # Attach the most recent build automatically
- ascelerate apps build attach-latest <bundle-id>
- ascelerate apps build attach-latest <bundle-id> --platform macos
- # Remove the attached build from a version
- ascelerate apps build detach <bundle-id>
- ```
- Build lookups are platform-aware: on universal-purchase apps, iOS and macOS builds can share build numbers, so the attach commands only consider builds matching the target version's platform.
- ### Phased Release
- ```bash
- # View phased release status
- ascelerate apps phased-release <bundle-id>
- # Enable phased release (starts inactive, activates when version goes live)
- ascelerate apps phased-release <bundle-id> --enable
- # Pause, resume, or complete a phased release
- ascelerate apps phased-release <bundle-id> --pause
- ascelerate apps phased-release <bundle-id> --resume
- ascelerate apps phased-release <bundle-id> --complete
- # Remove phased release entirely
- ascelerate apps phased-release <bundle-id> --disable
- ```
- ### Manual Release
- When a version's release option is set to manual, the approved version sits in Pending Developer Release until you release it:
- ```bash
- # Release the version that is pending developer release
- ascelerate apps release <bundle-id>
- # Target a specific version or platform
- ascelerate apps release <bundle-id> --version 2.1.0 --platform macos
- ```
- ### Age Rating
- ```bash
- # View age rating declaration
- ascelerate apps app-info age-rating <bundle-id>
- # Export age rating to JSON
- ascelerate apps app-info age-rating export <bundle-id>
- # Update age ratings from a JSON file
- ascelerate apps app-info age-rating import <bundle-id> --file age-rating.json
- ```
- The JSON file uses the same field names as the API. Only fields present in the file are updated:
- ```json
- {
- "isAdvertising": false,
- "isUserGeneratedContent": true,
- "violenceCartoonOrFantasy": "INFREQUENT_OR_MILD",
- "alcoholTobaccoOrDrugUseOrReferences": "NONE"
- }
- ```
- Intensity fields accept: `NONE`, `INFREQUENT_OR_MILD`, `FREQUENT_OR_INTENSE`. Boolean fields accept `true`/`false`.
- ### Routing App Coverage
- ```bash
- # View current routing coverage status
- ascelerate apps routing-coverage <bundle-id>
- # Upload a .geojson file
- ascelerate apps routing-coverage <bundle-id> --file coverage.geojson
- ```
- ### Localizations
- ```bash
- # View localizations (latest version by default)
- ascelerate apps localizations view <bundle-id>
- ascelerate apps localizations view <bundle-id> --version 2.1.0 --locale en-US
- # Export localizations to JSON
- ascelerate apps localizations export <bundle-id>
- ascelerate apps localizations export <bundle-id> --version 2.1.0 --output my-localizations.json
- # Update a single locale
- ascelerate apps localizations update <bundle-id> --whats-new "Bug fixes" --locale en-US
- # Bulk update from JSON file
- ascelerate apps localizations import <bundle-id> --file localizations.json
- ```
- The JSON format for export and bulk update:
- ```json
- {
- "en-US": {
- "description": "My app description.\n\nSecond paragraph.",
- "whatsNew": "- Bug fixes\n- New dark mode",
- "keywords": "productivity,tools,utility",
- "promotionalText": "Try our new features!",
- "marketingURL": "https://example.com",
- "supportURL": "https://example.com/support"
- },
- "de-DE": {
- "whatsNew": "- Fehlerbehebungen\n- Neuer Dunkelmodus"
- }
- }
- ```
- Only fields present in the JSON are updated -- omitted fields are left unchanged.
- ### Screenshots & App Previews
- ```bash
- # Download all screenshots and preview videos
- ascelerate apps media download <bundle-id>
- ascelerate apps media download <bundle-id> --folder my-media/ --version 2.1.0
- ascelerate apps media download <bundle-id> --locale en-US,tr
- # Upload screenshots and preview videos from a folder
- ascelerate apps media upload <bundle-id> media/
- # Upload from an archive (zip, tar, tar.gz supported)
- ascelerate apps media upload <bundle-id> screenshots.zip
- # Upload to a specific version
- ascelerate apps media upload <bundle-id> media/ --version 2.1.0
- # Replace existing media in matching sets before uploading
- ascelerate apps media upload <bundle-id> media/ --replace
- # Interactive mode: pick a folder or archive from the current directory
- ascelerate apps media upload <bundle-id>
- ```
- When the folder argument is omitted, the command lists all subdirectories and archive files in the current directory as a numbered picker. Archives (zip, tar, tar.gz) are extracted automatically before upload.
- Organize your media folder with locale and display type subfolders:
- ```
- media/
- ├── en-US/
- │ ├── APP_IPHONE_67/
- │ │ ├── 01_home.png
- │ │ ├── 02_settings.png
- │ │ └── preview.mp4
- │ └── APP_IPAD_PRO_3GEN_129/
- │ └── 01_home.png
- └── de-DE/
- └── APP_IPHONE_67/
- ├── 01_home.png
- └── 02_settings.png
- ```
- - **Level 1:** Locale (e.g. `en-US`, `de-DE`, `ja`)
- - **Level 2:** Display type folder name (see table below)
- - **Level 3:** Media files -- images (`.png`, `.jpg`, `.jpeg`) become screenshots, videos (`.mp4`, `.mov`) become app previews
- - Files are uploaded in alphabetical order by filename
- - Unsupported files are skipped with a warning
- #### Display types
- App Store Connect requires **`APP_IPHONE_67`** screenshots for iPhone apps and **`APP_IPAD_PRO_3GEN_129`** screenshots for iPad apps. All other display types are optional.
- | Folder name | Device | Screenshots | Previews |
- |---|---|---|---|
- | `APP_IPHONE_67` | iPhone 6.7" (iPhone 17 Pro Max, 16 Pro Max, 15 Pro Max) | **Required** | Yes |
- | `APP_IPAD_PRO_3GEN_129` | iPad Pro 12.9" (3rd gen+) | **Required** | Yes |
- <details>
- <summary>All optional display types</summary>
- | Folder name | Device | Screenshots | Previews |
- |---|---|---|---|
- | `APP_IPHONE_61` | iPhone 6.1" (iPhone 17 Pro, 16 Pro, 15 Pro) | Yes | Yes |
- | `APP_IPHONE_65` | iPhone 6.5" (iPhone 11 Pro Max, XS Max) | Yes | Yes |
- | `APP_IPHONE_58` | iPhone 5.8" (iPhone 11 Pro, X, XS) | Yes | Yes |
- | `APP_IPHONE_55` | iPhone 5.5" (iPhone 8 Plus, 7 Plus, 6s Plus) | Yes | Yes |
- | `APP_IPHONE_47` | iPhone 4.7" (iPhone SE 3rd gen, 8, 7, 6s) | Yes | Yes |
- | `APP_IPHONE_40` | iPhone 4" (iPhone SE 1st gen, 5s, 5c) | Yes | Yes |
- | `APP_IPHONE_35` | iPhone 3.5" (iPhone 4s and earlier) | Yes | Yes |
- | `APP_IPHONE_DUO` | iPhone Duo (uploaded through the asset library, see below) | Yes | No |
- | `PRODUCT_PAGE_HEADER` | Product page header image (asset library, see below) | Yes | No |
- | `APP_STORE_SEARCH_RESULTS` | App Store search results image (asset library, see below) | Yes | No |
- | `APP_IPAD_PRO_3GEN_11` | iPad Pro 11" | Yes | Yes |
- | `APP_IPAD_PRO_129` | iPad Pro 12.9" (1st/2nd gen) | Yes | Yes |
- | `APP_IPAD_105` | iPad 10.5" (iPad Air 3rd gen, iPad Pro 10.5") | Yes | Yes |
- | `APP_IPAD_97` | iPad 9.7" (iPad 6th gen and earlier) | Yes | Yes |
- | `APP_DESKTOP` | Mac | Yes | Yes |
- | `APP_APPLE_TV` | Apple TV | Yes | Yes |
- | `APP_APPLE_VISION_PRO` | Apple Vision Pro | Yes | Yes |
- | `APP_WATCH_ULTRA` | Apple Watch Ultra | Yes | No |
- | `APP_WATCH_SERIES_10` | Apple Watch Series 10 | Yes | No |
- | `APP_WATCH_SERIES_7` | Apple Watch Series 7 | Yes | No |
- | `APP_WATCH_SERIES_4` | Apple Watch Series 4 | Yes | No |
- | `APP_WATCH_SERIES_3` | Apple Watch Series 3 | Yes | No |
- | `IMESSAGE_APP_IPHONE_67` | iMessage iPhone 6.7" | Yes | No |
- | `IMESSAGE_APP_IPHONE_61` | iMessage iPhone 6.1" | Yes | No |
- | `IMESSAGE_APP_IPHONE_65` | iMessage iPhone 6.5" | Yes | No |
- | `IMESSAGE_APP_IPHONE_58` | iMessage iPhone 5.8" | Yes | No |
- | `IMESSAGE_APP_IPHONE_55` | iMessage iPhone 5.5" | Yes | No |
- | `IMESSAGE_APP_IPHONE_47` | iMessage iPhone 4.7" | Yes | No |
- | `IMESSAGE_APP_IPHONE_40` | iMessage iPhone 4" | Yes | No |
- | `IMESSAGE_APP_IPAD_PRO_3GEN_129` | iMessage iPad Pro 12.9" (3rd gen+) | Yes | No |
- | `IMESSAGE_APP_IPAD_PRO_3GEN_11` | iMessage iPad Pro 11" | Yes | No |
- | `IMESSAGE_APP_IPAD_PRO_129` | iMessage iPad Pro 12.9" (1st/2nd gen) | Yes | No |
- | `IMESSAGE_APP_IPAD_105` | iMessage iPad 10.5" | Yes | No |
- | `IMESSAGE_APP_IPAD_97` | iMessage iPad 9.7" | Yes | No |
- </details>
- > **Note:** Watch and iMessage display types support screenshots only -- video files in those folders are skipped with a warning. With `--replace`, each matching set ends up holding exactly the folder's files: screenshots and previews already uploaded stay as they are (recognized by their checksum, whatever their file name), the set's other items are deleted, only new or changed files are uploaded, and the set is put in the folder's order. A rerun with nothing changed uploads nothing, and renaming files to move them only reorders the set. iPhone Duo, header and search results images go through the asset library and are replaced whole.
- >
- > App Store Connect has no screenshot set for iPhone Duo: files in an `APP_IPHONE_DUO` folder go to the app's asset library and are placed on the version localization in file order. Accepted sizes are 2853×2007 / 2007×2853 (inner display, unfolded) and 2034×1398 / 1398×2034 (cover display); other sizes are rejected before upload. A file that still fails after retries makes `media upload` place that locale's iPhone Duo screenshots again at the end of the run, in file order. `media verify` lists them with file names and states and, given the folder, flags locales whose iPhone Duo files or order differ (a set holding the folder's files in another order is put in file order after you confirm, without uploading again); `media download` doesn't include them yet, and `media prune` never deletes them.
- >
- > `PRODUCT_PAGE_HEADER` and `APP_STORE_SEARCH_RESULTS` folders also go through the asset library, one image per locale each that isn't tied to a device class (the version shows it on iPhone, iPad and iPhone Duo alike), on every platform's versions: the product page header takes a PNG at 3840×1646 or 5244×2950, and the search results image a 3:2 JPG/PNG from 1920×1280 to 3840×2560 or a 5244×2950 PNG. Each slot also takes a video instead (header: 3840×1646; search results: 3:2 in the same size range; 5–30 s at 30 or 60 fps). Uploading replaces the locale's current image or video (the old one is removed after the new one is uploaded). An `APP_IPHONE_DUO` folder can hold app previews too (1920×886 or 886×1920, 15–30 s at 23–30 fps, with audio). Custom product pages take all three through `product-pages media upload --display-type PRODUCT_PAGE_HEADER` (or `APP_STORE_SEARCH_RESULTS`, `APP_IPHONE_DUO`). `media download` saves the library images; App Store Connect gives no download link for library videos.
- >
- > `media download` saves files in this same folder structure (defaults to `<bundle-id>-media/`), so you can download, edit, and re-upload.
- #### Designing App Store images
- `ascelerate screenshot setup-prompt --design` prints instructions for an AI coding agent to build a design generator: a small web app in the project's `app-store-screenshots/` folder that turns framed screenshots (`ascelerate screenshot frame`) into ad-style App Store images with headlines in every language, and exports them in the layout `media upload` takes:
- ```
- export/en-US/APP_IPHONE_67/01_hero.png
- export/en-US/APP_IPAD_PRO_3GEN_129/01_hero.png
- export/de-DE/APP_IPHONE_67/01_hero.png
- ```
- ```bash
- ascelerate apps media upload <bundle-id> export --platform ios --replace
- ```
- The [app-store-screenshots](https://github.com/keremerkan/ascelerate/tree/main/skills/app-store-screenshots) skill (`npx skills add keremerkan/ascelerate`) points agents to the same instructions.
- #### Verify and retry stuck media
- Sometimes screenshots or previews get stuck in "processing" after upload. Use `media verify` to check the status of all media at once and optionally retry stuck items:
- ```bash
- # Check status of all screenshots and previews
- ascelerate apps media verify <bundle-id>
- # Check a specific version
- ascelerate apps media verify <bundle-id> --version 2.1.0
- # Retry stuck items using local files from the media folder
- ascelerate apps media verify <bundle-id> media/
- ```
- Without `--folder`, the command shows a read-only status report. Sets where all items are complete show a compact one-liner; sets with stuck items expand to show each file and its state. With `--folder`, it prompts to retry stuck items by deleting them and re-uploading from the matching local files, preserving the original position order.
- A screenshot also counts as stuck when it reads complete but its asset library placement is still processing; App Review refuses a version in that state ("Asset is being processed"), and retrying with the folder uploads it again.
- #### Prune stale sets
- `--replace` on upload only changes sets that match a local folder — server sets for screen sizes you no longer ship (say, an old 5.8-inch set) keep their outdated screenshots. `media prune` deletes the sets that have no matching local locale/display-type folder, after listing them with asset counts and confirming:
- ```bash
- ascelerate apps media prune <bundle-id> media/
- ascelerate apps media prune <bundle-id> media/ --version 2.1.0 --platform ios
- ```
- Locales that have no local folder at all are skipped entirely — the command only prunes within locales the folder actually manages.
- #### Remove asset library images
- `media remove` takes one kind of asset library item off a version (the `PRODUCT_PAGE_HEADER` or `APP_STORE_SEARCH_RESULTS` image or video, or `APP_IPHONE_DUO` screenshots; `--previews` for Duo app previews), for the locales given with `--locale` or all of them, after listing what it found and asking:
- ```bash
- ascelerate apps media remove <bundle-id> PRODUCT_PAGE_HEADER --locale en-US
- ascelerate apps media remove <bundle-id> APP_IPHONE_DUO --locale en-US,tr --version 2.1.0
- ```
- #### Clean up the asset library
- Versions share the app's asset library images (a new version's screenshots are the previous version's images, and old versions keep theirs), so an image stays in use as long as any version, custom product page or event places it. When ascelerate removes a placement (`media remove`, `media upload --replace`, or replacing a header or search results image), it also deletes the image if nothing uses it any more and it never went through App Review. Earlier uploads can still have left unused images; `media library` counts the images and lists the unused ones, and `--delete-unused` deletes them after asking:
- ```bash
- ascelerate apps media library <bundle-id>
- ascelerate apps media library <bundle-id> --delete-unused
- ascelerate apps media library <bundle-id> --only APP_IPHONE_DUO --delete-unused
- ```
- `--only` narrows it to images that fit the given kinds, by asset category and pixel size: `PRODUCT_PAGE_HEADER`, `APP_STORE_SEARCH_RESULTS`, `APP_IPHONE_DUO`, a screenshot display type such as `APP_IPHONE_67`, or `UNFINISHED_UPLOADS` for uploads whose file never arrived, so the library can be cleaned one device type at a time. Images less than an hour old are always kept (an upload running at the same time may be about to place them), and a run that hits App Store Connect's hourly API limit stops and says how many are left.
- Images that went through App Review are never deleted, and each one is checked again right before it is deleted.
- ### Capturing Screenshots
- Capture App Store screenshots directly from iOS/iPadOS simulators using UI tests. Replaces [fastlane snapshot](https://docs.fastlane.tools/actions/snapshot/).
- ```bash
- # Let an AI coding agent set it up: UI tests, helper, screenshot mode with demo content, configuration
- ascelerate screenshot setup-prompt --copy # Copies instructions to paste into the agent (--design: a design generator)
- # Or by hand: generate config and helper files
- ascelerate screenshot init # Creates ascelerate/screenshot.yml and ascelerate/ScreenshotHelper.swift
- # Capture screenshots
- ascelerate screenshot run
- ascelerate screenshot run -l en-US,tr-TR # Only capture a subset of configured languages
- ascelerate screenshot run --json-events # Progress as JSON Lines on stdout for other tools
- ascelerate screenshot frame # Frame screenshots with device bezels
- ascelerate screenshot doctor [--json] # Check config and environment for problems
- ```
- The setup instructions start from what the project already has, so running `setup-prompt` again shows what's left. They also cover device frames, which you download from Apple's [design resources](https://developer.apple.com/design/resources/) (Product Bezels).
- Add `ScreenshotHelper.swift` to your UITest target, then call `setupScreenshots(app)` in `setUp()` and `screenshot("name")` to capture:
- ```swift
- override func setUp() {
- setupScreenshots(app)
- app.launch()
- }
- func testScreenshots() {
- screenshot("01-home")
- app.buttons["Settings"].tap()
- screenshot("02-settings")
- }
- ```
- On the iPhone Duo simulator (Xcode 27.1+), `setHinge(.open)` / `setHinge(.closed)` unfold and fold the device mid-test (it always boots folded). `deviceBezel` also takes a list of bezels; each screenshot is framed with the one whose screen fits its size, so folded and unfolded shots each get the right frame.
- Configure via `ascelerate/screenshot.yml`:
- ```yaml
- # workspace: MyApp.xcworkspace
- project: MyApp.xcodeproj
- scheme: AppUITests
- devices:
- - simulator: iPhone 17 Pro Max
- # frameDevice: true
- # deviceBezel: ./bezels/iPhone 17 Pro Max.png
- - simulator: iPad Pro 13-inch (M5)
- # frameDevice: true
- # deviceBezel: ./bezels/iPad Pro 13-inch (M5).png
- languages:
- - en-US
- - de-DE
- outputDirectory: ./screenshots
- # framedOutputDirectory: ./screenshots/framed
- clearPreviousScreenshots: true
- localizeSimulator: true
- overrideStatusBar: true
- # darkMode: false
- # disableAnimations: false
- # waitAfterBoot: 0
- # configuration: Debug
- # testplan: MyTestPlan
- # numberOfRetries: 0 # Retry failed languages (erase + reboot simulator)
- # stopAfterFirstError: false
- # reinstallApp: false
- # disableAssetDownloads: false # Disable mobileassetd (no Siri/keyboard/ML asset downloads; also blocks on-device ML assets)
- # xcargs: -maximum-parallel-testing-workers 2
- ```
- Features:
- - Builds once, then runs tests across all languages
- - iPhone and iPad run concurrently per language
- - Status bar override (9:41, full bars, no carrier)
- - Simulator localization per language
- - Dark mode support
- - Animation disabling for reliable captures
- - Automatic retries for failed languages (erases simulator, re-localizes, reboots, and reruns)
- - Errors skip and continue, with summary table and error logs saved to output
- - Helper version tracking with update warnings
- - Device bezel framing with [Apple Product Bezels](https://developer.apple.com/design/resources/#product-bezels) (download required)
- - Config validation via `doctor` subcommand
- - `create-helper` available separately but also run automatically by `init`
- Output structure:
- ```
- screenshots/
- ├── en-US/
- │ ├── iPhone-01-home.png
- │ └── iPad-01-home.png
- └── de-DE/
- └── ...
- ```
- With `frameDevice` enabled, framed screenshots are saved to `{outputDirectory}/framed/` (or `framedOutputDirectory` if set).
- ### App Info & Categories
- ```bash
- # View app info, categories, and per-locale metadata
- ascelerate apps app-info view <bundle-id>
- # List all available category IDs (no bundle ID needed)
- ascelerate apps app-info view --list-categories
- # Update localization fields for a single locale
- ascelerate apps app-info update <bundle-id> --name "My App" --subtitle "Best app ever"
- ascelerate apps app-info update <bundle-id> --locale de-DE --name "Meine App"
- # Update categories (can combine with localization flags)
- ascelerate apps app-info update <bundle-id> --primary-category UTILITIES
- ascelerate apps app-info update <bundle-id> --primary-category GAMES_ACTION --secondary-category ENTERTAINMENT
- # Export all app info localizations to JSON
- ascelerate apps app-info export <bundle-id>
- ascelerate apps app-info export <bundle-id> --output app-infos.json
- # Bulk update localizations from a JSON file
- ascelerate apps app-info import <bundle-id> --file app-infos.json
- ```
- ### Accessibility Declarations
- The App Store's accessibility labels, declared per device family:
- ```bash
- ascelerate apps accessibility <bundle-id> # view (draft/published per device)
- ascelerate apps accessibility set <bundle-id> --device iphone --supports voiceover,larger-text,dark-interface --publish
- ascelerate apps accessibility publish <bundle-id> # publish drafts unchanged
- ```
- `set` declares the full list: features you leave out are declared as not supported.
- ### Territory Availability
- ```bash
- # View which territories the app is available in
- ascelerate apps availability <bundle-id>
- # Show full country names
- ascelerate apps availability <bundle-id> --verbose
- # Make territories available or unavailable
- ascelerate apps availability <bundle-id> --add CHN,RUS
- ascelerate apps availability <bundle-id> --remove CHN
- ```
- ### App Pricing
- ```bash
- # Base price, prices set by hand and planned changes (--all: every territory; --json)
- ascelerate apps pricing <bundle-id>
- ascelerate apps pricing tiers <bundle-id> --territory USA
- # Base price, now or from a date (in the base territory's currency; 0 for free)
- ascelerate apps pricing set <bundle-id> --price 0.99
- ascelerate apps pricing set <bundle-id> --price 1.99 --start-date 2026-12-01
- # Prices set by hand: one territory, keep Apple's current prices, or give them back to Apple
- ascelerate apps pricing override <bundle-id> --territory FRA --price 0.99
- ascelerate apps pricing keep <bundle-id> --territories all
- ascelerate apps pricing remove <bundle-id> --territories FRA,DEU
- # Temporary price change (a sale), and removing a planned change
- ascelerate apps pricing sale <bundle-id> --territories all --price 0.49 --start-date 2026-12-20 --end-date 2026-12-27
- ascelerate apps pricing cancel <bundle-id> --territory USA --start-date 2026-12-01
- # Copy a schedule to another app (the iap pricing export format)
- ascelerate apps pricing export <bundle-id> --output prices.json
- ascelerate apps pricing import <other-bundle-id> --file prices.json [--snap]
- ```
- Apple derives the other territories' prices from the base price and may adjust them for tax and exchange rate changes; a price set by hand stays as it is. For several territories, `sale` takes the price in the base territory's currency and gives the others Apple's comparable prices; afterwards each territory's earlier price applies again. `import` replaces the whole schedule.
- ### Encryption Declarations
- ```bash
- # View existing encryption declarations
- ascelerate apps encryption <bundle-id>
- # Create a new encryption declaration
- ascelerate apps encryption <bundle-id> --create --description "Uses HTTPS for API communication"
- ascelerate apps encryption <bundle-id> --create --description "Uses AES encryption" --proprietary-crypto --third-party-crypto
- # Attach a compliance document to the newest declaration (or the one --declaration names)
- ascelerate apps encryption <bundle-id> --upload-document approval.pdf
- ```
- Some declarations need a document App Store Connect asks for, such as an export classification or France's encryption declaration. `--upload-document` attaches it to the newest declaration, or to the one `--declaration` names (the ID in the list); the list shows each declaration's document.
- ### App Tags
- ```bash
- # The tags Apple gives the app on the App Store, and where they're shown
- ascelerate apps tags <bundle-id> [--json]
- # Hide a tag on the App Store, or show it again
- ascelerate apps tags hide <bundle-id> "Photo Editing"
- ascelerate apps tags show <bundle-id> "Photo Editing"
- ```
- Apple chooses an app's tags; you can hide or show each one, by its name or ID.
- ### EULA
- ```bash
- # View the current EULA (or see that the standard Apple EULA applies)
- ascelerate apps eula <bundle-id>
- # Set a custom EULA from a text file
- ascelerate apps eula <bundle-id> --file eula.txt
- # Remove the custom EULA (reverts to standard Apple EULA)
- ascelerate apps eula <bundle-id> --delete
- ```
- ### Subscription Grace Period
- The grace period lets subscribers keep access for a short window after a failed renewal payment while Apple retries billing. Settings apply to the whole app.
- ```bash
- # View current grace period configuration
- ascelerate apps subscription-grace-period <bundle-id>
- # Enable for production with a 16-day window, applies to all renewals
- ascelerate apps subscription-grace-period <bundle-id> --opt-in true --duration SIXTEEN_DAYS --renewal-type ALL_RENEWALS
- # Sandbox testing only (production stays off)
- ascelerate apps subscription-grace-period <bundle-id> --sandbox-opt-in true --duration THREE_DAYS --renewal-type ALL_RENEWALS
- ```
- Valid `--duration` values: `THREE_DAYS`, `SIXTEEN_DAYS`, `TWENTY_EIGHT_DAYS`. Valid `--renewal-type` values: `ALL_RENEWALS`, `PAID_TO_PAID_ONLY`.
- Production can't be on without sandbox: turning on `--opt-in` turns sandbox on too, with a 16-day window for all renewals unless you pass others. Turning both off clears the duration and renewal type.
- ### Streamlined Purchasing
- Streamlined purchasing lets customers buy the app's subscriptions outside the app, such as on its App Store product page. It's on by default and applies to all the app's subscriptions. Apple turns it off only for an app whose latest approved build uses the StoreKit `PurchaseIntent` API; customers then subscribe from within the app.
- ```bash
- ascelerate apps streamlined-purchasing <bundle-id> # view
- ascelerate apps streamlined-purchasing <bundle-id> --enabled false # turn off
- ```
- ### Devices
- ```bash
- # List registered devices
- ascelerate devices list
- ascelerate devices list --platform IOS --status ENABLED
- # Show device details (interactive picker if name/UDID omitted)
- ascelerate devices info
- ascelerate devices info "My iPhone"
- # Register a new device (interactive prompts if options omitted)
- ascelerate devices register
- ascelerate devices register --name "My iPhone" --udid 00008101-XXXXXXXXXXXX --platform IOS
- # Update a device (interactive picker and update prompts if omitted)
- ascelerate devices update
- ascelerate devices update "My iPhone" --name "Work iPhone"
- ascelerate devices update "My iPhone" --status DISABLED
- ```
- ### Certificates
- ```bash
- # List signing certificates
- ascelerate certs list
- ascelerate certs list --type DISTRIBUTION
- # Show certificate details (interactive picker if omitted)
- ascelerate certs info
- ascelerate certs info "Apple Distribution: Example Inc"
- # Create a certificate (interactive type picker if --type omitted)
- # Auto-generates RSA key pair and CSR, imports into login keychain
- ascelerate certs create
- ascelerate certs create --type DISTRIBUTION
- ascelerate certs create --type DEVELOPMENT --csr my-request.pem
- # Revoke a certificate (interactive picker if omitted)
- ascelerate certs revoke
- ascelerate certs revoke ABC123DEF456
- ```
- ### Bundle Identifiers
- ```bash
- # List bundle identifiers
- ascelerate bundle-ids list
- ascelerate bundle-ids list --platform IOS
- # Show details and capabilities (interactive picker if omitted)
- ascelerate bundle-ids info
- ascelerate bundle-ids info com.example.MyApp
- # Register a new bundle ID (interactive prompts if options omitted)
- ascelerate bundle-ids register
- ascelerate bundle-ids register --name "My App" --identifier com.example.MyApp --platform IOS
- # Rename a bundle ID (identifier itself is immutable)
- ascelerate bundle-ids update
- ascelerate bundle-ids update com.example.MyApp --name "My Renamed App"
- # Delete a bundle ID (interactive picker if omitted)
- ascelerate bundle-ids delete
- ascelerate bundle-ids delete com.example.MyApp
- # Enable a capability (interactive pickers if omitted)
- # Shows only capabilities not already enabled
- ascelerate bundle-ids enable-capability
- ascelerate bundle-ids enable-capability com.example.MyApp --type PUSH_NOTIFICATIONS
- # Disable a capability (picks from currently enabled capabilities)
- ascelerate bundle-ids disable-capability
- ascelerate bundle-ids disable-capability com.example.MyApp
- ```
- After enabling or disabling a capability, if provisioning profiles exist for that bundle ID, the command offers to regenerate them (required for changes to take effect).
- > **Note:** Some capabilities (e.g. App Groups, iCloud, Associated Domains) require additional configuration in the [Apple Developer portal](https://developer.apple.com/account/resources) after enabling.
- ### Provisioning Profiles
- ```bash
- # List provisioning profiles
- ascelerate profiles list
- ascelerate profiles list --type IOS_APP_STORE --state ACTIVE
- # Show profile details (interactive picker if omitted)
- ascelerate profiles info
- ascelerate profiles info "My App Store Profile"
- # Download a profile (interactive picker if omitted)
- ascelerate profiles download
- ascelerate profiles download "My App Store Profile" --output ./profiles/
- # Create a profile (fully interactive if options omitted)
- # Prompts for name, type, bundle ID, certificates, and devices
- ascelerate profiles create
- ascelerate profiles create --name "My Profile" --type IOS_APP_STORE --bundle-id com.example.MyApp --certificates all
- # --certificates all uses all certs of the matching family (distribution, development, or Developer ID)
- # You can also specify serial numbers: --certificates ABC123,DEF456
- # Delete a profile (interactive picker if omitted)
- ascelerate profiles delete
- ascelerate profiles delete "My App Store Profile"
- # Reissue profiles (delete + recreate with latest certs of matching family)
- ascelerate profiles reissue # Interactive: pick from all profiles (shows status)
- ascelerate profiles reissue "My Profile" # Reissue a specific profile by name
- ascelerate profiles reissue --all-invalid # Reissue all invalid profiles
- ascelerate profiles reissue --all # Reissue all profiles regardless of state
- ascelerate profiles reissue --all --all-devices # Reissue all, using all enabled devices for dev/adhoc
- ascelerate profiles reissue --all --to-certs ABC123,DEF456 # Use specific certificates instead of auto-detect
- ```
- ### Builds
- ```bash
- # List all builds (shows app version, platform, and build number)
- ascelerate builds list
- ascelerate builds list --bundle-id <bundle-id>
- ascelerate builds list --bundle-id <bundle-id> --version 2.1.0
- ascelerate builds list --bundle-id <bundle-id> --platform macos
- # Archive an Xcode project
- ascelerate builds archive
- ascelerate builds archive --scheme MyApp --output ./archives
- ascelerate builds archive --scheme MyApp --json-events # progress as JSON Lines on stdout for other tools
- ascelerate builds archive --scheme MyApp --build-number 9 # build 9 for the app, its extensions and watch app (the project is left as it is)
- ascelerate builds archive --scheme MyApp --build-number auto # the app's number, or the one after the highest uploaded when that's taken; extensions get the same
- ascelerate builds archive --scheme MyApp --xcodebuild-output quiet # xcodebuild's warnings and errors only (full: everything)
- ascelerate settings --xcodebuild-output quiet # the default for every archive (~/.ascelerate/settings.json; ASCELERATE_XCODEBUILD_OUTPUT for one run)
- ascelerate builds archives # Xcode's archives, newest first (--bundle-id, --platform, --json)
- # Validate a build before uploading
- ascelerate builds validate MyApp.ipa
- # Upload a build to App Store Connect
- ascelerate builds upload MyApp.ipa
- ascelerate builds upload --latest --bundle-id com.example.MyApp --platform macos # the newest archive of an app for one platform
- ascelerate builds upload MyApp.ipa --api # upload through the App Store Connect API instead of altool (.ipa or Mac .pkg)
- ascelerate builds upload MyApp.xcarchive --api --bundle-id com.example.MyApp # refuse a file holding another app
- ascelerate builds upload MyApp.ipa --api --json-events # progress as JSON Lines on stdout for other tools
- ascelerate builds uploads <bundle-id> # recent uploads with their state and Apple's errors/warnings
- ascelerate builds uploads <bundle-id> --delete-stale # remove upload records that will never complete
- # Wait for a build to finish processing
- ascelerate builds await-processing <bundle-id>
- ascelerate builds await-processing <bundle-id> --build-version 903
- ascelerate builds await-processing <bundle-id> --build-version 903 --platform macos
- ```
- The `archive` command auto-detects the `.xcworkspace` or `.xcodeproj` in the current directory and resolves the scheme if only one exists. It accepts `.ipa`, `.pkg`, or `.xcarchive` files for `upload` and `validate`. When given an `.xcarchive`, it detects the archive's platform and automatically exports to `.ipa` (iOS-family) or `.pkg` (macOS) before uploading, passing the matching platform to altool. An archive signed with App Store distribution profiles (a project signed manually) is exported with the installed App Store profiles of its app and extensions, so Xcode creates none; other archives are exported with automatic signing.
- ### TestFlight
- ```bash
- # Beta groups
- ascelerate testflight groups list <bundle-id>
- ascelerate testflight groups info <bundle-id> "External Testers"
- ascelerate testflight groups create <bundle-id> --name "Friends" --public-link --public-link-limit 100
- ascelerate testflight groups update <bundle-id> "Friends" --public-link false
- ascelerate testflight groups update <bundle-id> "Friends" --mac false --vision-pro true # iPhone/iPad builds on Apple silicon Macs, Vision Pro
- ascelerate testflight groups delete <bundle-id> "Friends"
- # Give a group access to a build (defaults to the latest)
- ascelerate testflight groups add-build <bundle-id> "Friends"
- ascelerate testflight groups add-build <bundle-id> "Friends" --build 123
- ascelerate testflight groups remove-build <bundle-id> "Friends" --build 123
- # Public-link recruitment criteria (device/OS filters); Apple no longer adds new ones, set only replaces existing criteria
- ascelerate testflight groups criteria view <bundle-id> "Friends" --options
- ascelerate testflight groups criteria set <bundle-id> "Friends" --filter IPHONE:18.0 --filter IPAD:17.0:26
- ascelerate testflight groups criteria clear <bundle-id> "Friends"
- # Testers
- ascelerate testflight testers list <bundle-id> --group "Friends"
- ascelerate testflight testers add <bundle-id> --email tester@example.com --group "Friends"
- ascelerate testflight testers remove <bundle-id> tester@example.com --group "Friends"
- ascelerate testflight testers remove <bundle-id> tester@example.com # remove from the whole app
- ascelerate testflight testers invite <bundle-id> tester@example.com # re-send the invitation email
- ascelerate testflight testers import <bundle-id> --file testers.csv --group "Friends"
- # Builds & distribution
- ascelerate testflight builds <bundle-id> # TestFlight states per build
- ascelerate testflight versions <bundle-id> # pre-release version trains
- ascelerate testflight status <bundle-id> --build 123 # processing, testing, and beta review states
- ascelerate testflight expire <bundle-id> --build 123
- ascelerate testflight notify <bundle-id> # notify testers about the latest build
- ascelerate testflight auto-notify <bundle-id> --enabled true
- # What to Test (per build, per locale)
- ascelerate testflight what-to-test view <bundle-id>
- ascelerate testflight what-to-test set <bundle-id> --text "Bug fixes" --locale en-US
- ascelerate testflight what-to-test set <bundle-id> --text "Bug fixes" # all existing locales
- ascelerate testflight what-to-test copy <bundle-id> --platform ios # newest build gets the newest earlier build's notes
- ascelerate testflight what-to-test export <bundle-id> --output notes.json
- ascelerate testflight what-to-test import <bundle-id> --file notes.json
- # Beta review (required for external testing)
- ascelerate testflight submit <bundle-id>
- ascelerate testflight app-info view <bundle-id>
- ascelerate testflight app-info update <bundle-id> --locale en-US --feedback-email me@example.com
- ascelerate testflight review-info <bundle-id> # contact + demo account; pass flags to update
- ascelerate testflight eula <bundle-id> --file eula.txt # custom beta license agreement
- # Tester feedback
- ascelerate testflight feedback crashes list <bundle-id>
- ascelerate testflight feedback crashes log <submission-id> --output crash.log
- ascelerate testflight feedback screenshots list <bundle-id>
- ascelerate testflight feedback screenshots download <bundle-id> # picker; zips screenshots + comment
- ```
- Build-scoped commands default to the latest non-expired build; pass `--build <number>` (and `--platform` for universal-purchase apps) to target a specific one. `testers import` reads one tester per line (`email[,first name[,last name]]`), skipping blank lines, `#` comments, and a leading header row.
- ### In-App Purchases
- ```bash
- # List and inspect
- ascelerate iap list <bundle-id>
- ascelerate iap list <bundle-id> --type consumable --state approved
- ascelerate iap info <bundle-id> <product-id>
- # Promoted purchases (shown on the App Store product page)
- ascelerate iap promoted list <bundle-id>
- ascelerate iap promoted add <bundle-id> <product-id>
- ascelerate iap promoted reorder <bundle-id> com.example.a,com.example.b
- ascelerate iap promoted toggle <bundle-id> <product-id> --enabled false
- ascelerate iap promoted remove <bundle-id> <product-id>
- # Create, update, and delete
- ascelerate iap create <bundle-id> --name "100 Coins" --product-id <product-id> --type CONSUMABLE
- ascelerate iap update <bundle-id> <product-id> --name "100 Gold Coins"
- ascelerate iap delete <bundle-id> <product-id>
- # Submit for review
- ascelerate iap submit <bundle-id> <product-id>
- # Manage localizations
- ascelerate iap localizations view <bundle-id> <product-id>
- ascelerate iap localizations export <bundle-id> <product-id>
- ascelerate iap localizations import <bundle-id> <product-id> --file iap-de.json
- # Pricing — set the base region price (auto-equalizes to all other territories)
- ascelerate iap pricing show <bundle-id> <product-id>
- ascelerate iap pricing tiers <bundle-id> <product-id> --territory USA
- ascelerate iap pricing set <bundle-id> <product-id> --price 4.99
- ascelerate iap pricing set <bundle-id> <product-id> --price 4.99 --base-territory GBR
- # Pricing — manage per-territory manual overrides
- ascelerate iap pricing override <bundle-id> <product-id> --price 5.99 --territory FRA
- ascelerate iap pricing remove <bundle-id> <product-id> --territory FRA
- # Pricing — copy the schedule between products (same app or another one)
- ascelerate iap pricing export <bundle-id> <product-id> --output prices.json
- ascelerate iap pricing import <other-bundle-id> <other-product-id> --file prices.json
- # Per-IAP territory availability (independent of the app's territories)
- ascelerate iap availability <bundle-id> <product-id>
- ascelerate iap availability <bundle-id> <product-id> --add CHN,RUS --remove ITA --available-in-new-territories true
- # Offer codes (campaigns + redeem codes)
- ascelerate iap offer-code list <bundle-id> <product-id>
- ascelerate iap offer-code create <bundle-id> <product-id> --name "Launch Promo" --eligibility NON_SPENDER,ACTIVE_SPENDER --price 0.99 --territory USA --equalize-all-territories
- ascelerate iap offer-code toggle <bundle-id> <product-id> <offer-code-id> --active true
- ascelerate iap offer-code gen-codes <bundle-id> <product-id> <offer-code-id> --count 100 --expires 2026-12-31
- ascelerate iap offer-code add-custom-codes <bundle-id> <product-id> <offer-code-id> --code PROMO2026 --count 1000 --expires 2026-12-31
- ascelerate iap offer-code view-codes <one-time-use-batch-id> --output codes.txt
- # Promotional images + App Review screenshot
- ascelerate iap images list <bundle-id> <product-id>
- ascelerate iap images upload <bundle-id> <product-id> ./hero.png
- ascelerate iap images delete <bundle-id> <product-id> <image-id>
- ascelerate iap review-screenshot view <bundle-id> <product-id>
- ascelerate iap review-screenshot upload <bundle-id> <product-id> ./review.png
- ascelerate iap review-screenshot delete <bundle-id> <product-id>
- ```
- Filter values are case-insensitive. Types: `CONSUMABLE`, `NON_CONSUMABLE`, `NON_RENEWING_SUBSCRIPTION`. States: `APPROVED`, `MISSING_METADATA`, `READY_TO_SUBMIT`, `WAITING_FOR_REVIEW`, `IN_REVIEW`, etc.
- `iap info` and `iap pricing show` warn when an IAP has no price schedule — the same condition surfaced in `apps review preflight` (which skips products you removed from sale instead of failing them). When `set` changes the base territory price, existing per-territory manual overrides are preserved by default. If overrides exist, an interactive menu offers to revert any of them; pass `--remove-all-overrides` for a non-interactive wipe.
- `iap pricing export` writes the base territory and every manual price to a JSON file keyed by territory code; `iap pricing import` applies such a file to any IAP — prices are matched to the target product's own tiers by customer price, so the file works across products and apps. Import replaces the schedule wholesale: territories not listed in the file revert to auto-equalize. If the current schedule already matches the file, import is a no-op. A price that isn't one of the target's tiers fails the import, which lists the nearest tiers; with `--snap`, each such price takes the nearest tier instead (the cheaper when two are as close), and the snapped prices are listed before you confirm.
- Offer code one-time-use codes are generated asynchronously. After `gen-codes`, run `view-codes <batch-id>` to fetch the actual code values. If the response is empty, retry in a few seconds. Custom codes (`add-custom-codes`) are developer-supplied strings that don't need separate generation.
- Images and review screenshots use Apple's 3-step file upload flow (reserve → PUT chunks → commit with MD5). The CLI handles all three steps in `upload`.
- ### Subscriptions
- ```bash
- # List and inspect
- ascelerate sub groups <bundle-id>
- ascelerate sub list <bundle-id>
- ascelerate sub info <bundle-id> <product-id>
- # Create, update, and delete subscriptions
- ascelerate sub create <bundle-id> --name "Monthly" --product-id <product-id> --period ONE_MONTH --group-id <group-id>
- ascelerate sub update <bundle-id> <product-id> --name "Monthly Plan"
- ascelerate sub delete <bundle-id> <product-id>
- # Manage subscription groups
- ascelerate sub create-group <bundle-id> --name "Premium"
- ascelerate sub update-group <bundle-id> --name "Premium Plus"
- ascelerate sub delete-group <bundle-id>
- # Submit for review
- ascelerate sub submit <bundle-id> <product-id>
- # Subscription localizations
- ascelerate sub localizations view <bundle-id> <product-id>
- ascelerate sub localizations export <bundle-id> <product-id>
- ascelerate sub localizations import <bundle-id> <product-id> --file sub-de.json
- # Subscription group localizations
- ascelerate sub group-localizations view <bundle-id>
- ascelerate sub group-localizations export <bundle-id>
- ascelerate sub group-localizations import <bundle-id> --file group-de.json
- # Pricing — single territory or fan-out across all territories
- ascelerate sub pricing show <bundle-id> <product-id>
- ascelerate sub pricing tiers <bundle-id> <product-id> --territory USA
- ascelerate sub pricing set <bundle-id> <product-id> --price 4.99 --territory USA
- ascelerate sub pricing set <bundle-id> <product-id> --price 4.99 --equalize-all-territories
- # Standard global price raise: grandfather existing subscribers at the old price
- ascelerate sub pricing set <bundle-id> <product-id> --price 9.99 --equalize-all-territories --preserve-current
- # Pricing — copy per-territory prices between subscriptions (same app or another one)
- ascelerate sub pricing export <bundle-id> <product-id> --output prices.json
- ascelerate sub pricing import <other-bundle-id> <other-product-id> --file prices.json --preserve-current
- # Per-subscription territory availability (independent of the app's territories)
- ascelerate sub availability <bundle-id> <product-id>
- ascelerate sub availability <bundle-id> <product-id> --add CHN,RUS --remove ITA --available-in-new-territories true
- ascelerate sub availability <bundle-id> <product-id> --plan monthly # the "Monthly with 12-Month Commitment" plan of an annual subscription
- # Introductory offers (free trials and intro discounts for new subscribers)
- ascelerate sub intro-offer list <bundle-id> <product-id>
- ascelerate sub intro-offer create <bundle-id> <product-id> --mode FREE_TRIAL --duration ONE_WEEK --periods 1 --territories all
- ascelerate sub intro-offer create <bundle-id> <product-id> --mode PAY_AS_YOU_GO --duration ONE_MONTH --periods 3 --territories USA --price 0.99
- ascelerate sub intro-offer update <bundle-id> <product-id> <offer-id> --end-date 2026-12-31
- ascelerate sub intro-offer delete <bundle-id> <product-id> <offer-id>
- # Promotional offers (server-signed offers for existing subscribers)
- ascelerate sub promo-offer list <bundle-id> <product-id>
- ascelerate sub promo-offer create <bundle-id> <product-id> --name "Loyalty 50%" --code LOYALTY50 --mode PAY_AS_YOU_GO --duration ONE_MONTH --periods 3 --price 4.99 --territory USA --equalize-all-territories
- ascelerate sub promo-offer update <bundle-id> <product-id> <offer-id> --price 5.99 --equalize-all-territories
- ascelerate sub promo-offer delete <bundle-id> <product-id> <offer-id>
- # Retention messages (shown to subscribers who go to cancel) and retention offers
- ascelerate sub retention-message list <bundle-id>
- ascelerate sub retention-message create <bundle-id> --name "Stay with us" --locale en-US --header "Before you go" --body "Your plan gets new features every month."
- ascelerate sub retention-message localizations set <bundle-id> "Stay with us" --locale de-DE --header "Bevor Sie gehen" --body "Ihr Abo erhält jeden Monat neue Funktionen."
- ascelerate sub retention-message image upload <bundle-id> "Stay with us" ./retention.png
- ascelerate sub retention-message submit <bundle-id> "Stay with us"
- ascelerate sub retention-offer create <bundle-id> <product-id> --name "Half off" --offer-id stay.half --mode PAY_AS_YOU_GO --duration ONE_MONTH --periods 3 --paid-months 6 --price 4.99 --territories all
- ascelerate sub retention-message assign <bundle-id> <product-id> "Stay with us" --offers stay.half
- # Win-back offers (for people whose subscription ended; approved subscriptions only)
- ascelerate sub win-back-offer list <bundle-id> <product-id>
- ascelerate sub win-back-offer create <bundle-id> <product-id> --name "Come back" --offer-id comeback.half --mode PAY_AS_YOU_GO --duration ONE_MONTH --periods 3 --since-months 3-12 --paid-months 6 --price 4.99 --territories all
- ascelerate sub win-back-offer update <bundle-id> <product-id> comeback.half --end-date 2027-03-31
- ascelerate sub win-back-offer delete <bundle-id> <product-id> comeback.half
- # Offer codes (redeemable codes — one-time-use batches and custom codes)
- ascelerate sub offer-code list <bundle-id> <product-id>
- ascelerate sub offer-code create <bundle-id> <product-id> --name "Launch Free Month" --eligibility NEW --offer-eligibility STACK_WITH_INTRO_OFFERS --mode FREE_TRIAL --duration ONE_MONTH --periods 1 --price 0 --territory USA --equalize-all-territories
- ascelerate sub offer-code toggle <bundle-id> <product-id> <offer-code-id> --active true
- ascelerate sub offer-code gen-codes <bundle-id> <product-id> <offer-code-id> --count 500 --expires 2026-12-31
- ascelerate sub offer-code add-custom-codes <bundle-id> <product-id> <offer-code-id> --code SUBPROMO --count 1000 --expires 2026-12-31
- ascelerate sub offer-code view-codes <one-time-use-batch-id> --output codes.txt
- # Submit a subscription group for review (mirror of `sub submit` but for the whole group)
- ascelerate sub submit-group <bundle-id>
- # Promotional images + App Review screenshot
- ascelerate sub images list <bundle-id> <product-id>
- ascelerate sub images upload <bundle-id> <product-id> ./hero.png
- ascelerate sub images delete <bundle-id> <product-id> <image-id>
- ascelerate sub review-screenshot view <bundle-id> <product-id>
- ascelerate sub review-screenshot upload <bundle-id> <product-id> ./review.png
- ascelerate sub review-screenshot delete <bundle-id> <product-id>
- ```
- When submitting an app version for review, `apps review submit` automatically detects IAPs and subscriptions with pending changes and offers to submit them alongside the app version. Pending changes are read from each product's version history (a version in Prepare for Submission, Ready for Review, or a rejected state), so screenshot-only edits are detected too. The same check drives `iap submit`, `sub submit`, and `sub submit-group`: any product with a pending version can be submitted, including approved products with edits since their last approval, and without one the command stops before making any request. `iap info` and `sub info` show the pending version, and `apps review status` resolves the items of active submissions to the app version or product they refer to. It also offers to add the Game Center achievements, leaderboards, sets, activities and challenges whose changes wait for review, and warns when Game Center is off on the version.
- The localization import commands create missing locales automatically with confirmation, so you can add new languages without visiting App Store Connect.
- `sub intro-offer` is for new subscribers (free trials and intro discounts). `sub promo-offer` is for existing subscribers (requires server-side signing of the offer payload at runtime). `sub retention-message` sets what the App Store shows subscribers who go to cancel (a header, body and image per version, reviewed by App Review), and `sub retention-offer` the offers it can show them. `sub offer-code` produces redeemable code campaigns — one-time-use batches generate asynchronously (use `view-codes <batch-id>` to fetch values), while custom codes are developer-supplied strings.
- Images and review screenshots use Apple's 3-step upload flow (reserve → PUT chunks → commit with MD5) — `upload` handles all three steps.
- **Win-back offers** (`sub win-back-offer`) are for people whose subscription ended: eligibility by months since they last subscribed, months paid and time since their last offer, from a start date to an optional end date, with a priority and optional App Store promotion. Only approved subscriptions take them. Apple's API specification leaves their prices' territory and price point out; ascelerate adds them when it prepares the specification, as for retention offers.
- Subscription pricing is per-territory. There is no auto-equalize concept like IAPs have, so `--equalize-all-territories` mirrors what the App Store Connect web UI does behind the scenes: looks up the equivalent local-currency tier in every territory and POSTs one price record per territory.
- Apple treats price changes differently for existing subscribers depending on direction — `sub pricing set` enforces this:
- - **Decrease**: existing subscribers automatically move to the lower price. Interactive runs prompt; `--yes` mode requires `--confirm-decrease` to acknowledge the revenue impact.
- - **Increase**: you must explicitly choose how to handle existing subscribers. Errors unless `--preserve-current` (grandfather them at the old price) or `--no-preserve-current` (push them to the new price after Apple's notification period) is set. Same rule applies aggregated across `--equalize-all-territories`.
- - **New territory** (no existing price): no existing subscribers to consider; flags optional.
- - **Unchanged**: skipped silently.
- `sub pricing export` writes every territory's current customer price to a JSON file (preserved/grandfathered and future-scheduled prices are excluded); `sub pricing import` applies such a file to any subscription — prices are matched to the target subscription's own tiers by customer price, so the file works across products and apps. Import only touches listed territories, skips ones already at the listed price, and enforces the same increase/decrease safety rules as `sub pricing set`. A price that isn't one of the target's tiers fails the import, which lists the nearest tiers; with `--snap`, each such price takes the nearest tier instead (the cheaper when two are as close), and the snapped prices are listed before you confirm.
- Multi-territory price writes retry transient App Store Connect errors (HTTP 429/5xx) automatically — first in place with backoff, then in a second sweep at the end of the run. Territories that still fail are listed in the final report and the command exits non-zero; re-running the same command retries just those, since already-updated territories are skipped as unchanged.
- ### Sandbox Testers
- The Apple Accounts that buy in-app purchases and subscriptions in the sandbox (created in App Store Connect; the API lists and changes them):
- ```bash
- ascelerate sandbox-testers # list: storefront, renewal rate, interrupted purchases
- ascelerate sandbox-testers update tester@example.com --renewal-rate 3m --territory DEU
- ascelerate sandbox-testers clear-history tester@example.com # or --all
- ```
- ### Customer Reviews
- ```bash
- # List reviews (newest first by default)
- ascelerate reviews list <bundle-id>
- ascelerate reviews list <bundle-id> --rating 1 --sort critical --unanswered --limit 20
- ascelerate reviews list <bundle-id> --territory USA
- # Full review text + developer response
- ascelerate reviews info <review-id>
- # Publish (or replace) a developer response
- ascelerate reviews respond <review-id> --body "Thanks for the feedback! ..."
- # Delete the developer response
- ascelerate reviews delete-response <review-id>
- ```
- Reviews are read-only — you can only manage the developer response. `--sort` accepts `recent`, `oldest`, `critical` (lowest rating first), or `best`. Review IDs come from `reviews list`. With `--json`, `reviews list` includes full review bodies and developer responses, so no per-review `info` calls are needed.
- ### Game Center
- Achievements, leaderboards and leaderboard sets, with their languages, images and order:
- ```bash
- ascelerate game-center <bundle-id> # on or off, counts, default leaderboard
- ascelerate game-center enable <bundle-id> # can't be turned off again through the API
- ascelerate game-center achievements create <bundle-id> --id first.win --name "First Win" --points 10
- ascelerate game-center achievements localizations set <bundle-id> first.win --locale en-US \
- --name "First Win" --before-earned "Win a round." --after-earned "You won a round."
- ascelerate game-center achievements image upload <bundle-id> first.win --locale en-US icon.png
- ascelerate game-center leaderboards create <bundle-id> --id high.score --name "High Score"
- ascelerate game-center leaderboards create <bundle-id> --id weekly.time --name "Weekly Time" \
- --formatter elapsed-time-second --sort low --recurrence-start 2026-12-07T00:00:00Z \
- --recurrence-duration PT168H --recurrence-rule "FREQ=DAILY;INTERVAL=7"
- ascelerate game-center sets create <bundle-id> --id all.scores --name "All Scores" --leaderboards high.score,weekly.time
- ascelerate game-center activities create <bundle-id> --id duel --name "Duel" --play-style sync --min-players 2 --max-players 2
- ascelerate game-center activities link <bundle-id> duel --achievements first.win --leaderboards high.score
- ascelerate game-center challenges create <bundle-id> --id beat.score --name "Beat My Score" --leaderboard high.score --repeatable
- ascelerate game-center achievements reorder <bundle-id> first.win,high.five
- ascelerate game-center achievements submit <bundle-id> first.win # add its new version to the draft submission
- ```
- Achievements, leaderboards, sets, activities and challenges share `info`, `update`, `delete`, `localizations` (view, set, export, import, delete), `image` (upload, delete; activities and challenges also a version's `--default` image) and `submit`; the first three also `reorder`. Their text and images live on a version; changing a live one makes its next version first. Images are square, at least 512×512.
- Groups share these items between a team's apps; adding an app to a group can't be undone, so try it with `--dry-run`:
- ```bash
- ascelerate game-center groups # the team's groups with their apps
- ascelerate game-center groups create --name "My Games"
- ascelerate game-center groups add-app "My Games" <bundle-id> --dry-run
- ```
- Rule-based matchmaking belongs to the team, so it takes no bundle ID:
- ```bash
- ascelerate game-center matchmaking rule-sets create --name Ranked --min 2 --max 4
- ascelerate game-center matchmaking rules add Ranked --name SameVersion --type compatible \
- --expression "requests[0].appVersion == requests[1].appVersion" --description "Same app version"
- ascelerate game-center matchmaking teams add Ranked --name Red --min 1 --max 2
- ascelerate game-center matchmaking queues create --name RankedQueue --rule-set Ranked
- ascelerate game-center matchmaking test Ranked --file requests.json # the matches Apple would make
- ```
- ### Featuring Nominations
- Tell Apple's editorial team about a launch, an update or new content:
- ```bash
- ascelerate nominations # list (drafts, submitted, archived)
- ascelerate nominations create --app <bundle-id> --type enhancements --name "Version 5" \
- --description "What's new and why it matters" --publish-start 2026-11-01 --devices iphone,ipad
- ascelerate nominations submit <id> # send a draft to Apple
- ascelerate nominations update <id> --publish-start 2026-11-08
- ascelerate nominations archive <id>
- ascelerate nominations delete <id>
- ```
- `create` saves a draft unless you pass `--submit`. Types: `launch`, `enhancements`, `new-content`.
- ### Users
- The team's people and invitations: roles, the apps they see, access to Certificates, Identifiers & Profiles:
- ```bash
- ascelerate users # everyone, with roles and app access
- ascelerate users info someone@example.com
- ascelerate users update someone@example.com --roles developer,marketing --apps com.example.app
- ascelerate users invite --email new@example.com --first-name Ada --last-name Lovelace --roles developer
- ascelerate users invitations # pending, with expiry; cancel-invitation withdraws one
- ascelerate users remove someone@example.com
- ```
- ### Webhooks
- Have App Store Connect POST an app's events (review state changes, build uploads, TestFlight feedback, …) to your server:
- ```bash
- ascelerate webhooks <bundle-id> # list
- ascelerate webhooks create <bundle-id> --name "Release bot" --url https://example.com/hook \
- --events app-store-version-app-version-state-updated,build-upload-state-updated
- ascelerate webhooks ping <bundle-id> "Release bot" # send a test event
- ascelerate webhooks deliveries <bundle-id> "Release bot" --state failed
- ascelerate webhooks redeliver <delivery-id>
- ascelerate webhooks update <bundle-id> "Release bot" --enabled false
- ascelerate webhooks delete <bundle-id> "Release bot"
- ```
- Without `--secret`, `create` generates a signing secret and prints it once. `--events all` subscribes to every event type.
- ### Xcode Cloud
- Follow and start Xcode Cloud builds. A product is set up once in Xcode (Integrate > Create Workflow); after that:
- ```bash
- ascelerate xcode-cloud products # apps and frameworks
- ascelerate xcode-cloud workflows <bundle-id> # list; also info, enable, disable, delete
- ascelerate xcode-cloud workflows update <bundle-id> "Default" --manual-only # stop automatic builds
- ascelerate xcode-cloud workflows update <bundle-id> "Release" --branch-changes "main,release/*" --xcode "Xcode 27.2"
- ascelerate xcode-cloud workflows create <bundle-id> --like "Default" --name "TestFlight" --action archive:MyApp:ios
- ascelerate xcode-cloud runs <bundle-id> [--workflow "Release"] # build runs, newest first
- ascelerate xcode-cloud runs info <bundle-id> 42 # details, actions, the build it uploaded
- ascelerate xcode-cloud runs issues <bundle-id> 42 # errors and warnings
- ascelerate xcode-cloud runs tests <bundle-id> 42 --failed
- ascelerate xcode-cloud runs logs <bundle-id> 42 --show ci_post_clone.log # log bundle: post-clone, packages, xcodebuild
- ascelerate xcode-cloud runs artifacts <bundle-id> 42 --download ./artifacts
- ascelerate xcode-cloud start <bundle-id> "Release" --branch main # or --tag, --pull-request
- ascelerate xcode-cloud rerun <bundle-id> 42
- ascelerate xcode-cloud xcode-versions # Xcode and macOS versions offered
- ```
- ### In-App Events
- ```bash
- # List and inspect
- ascelerate events list <bundle-id>
- ascelerate events list <bundle-id> --state PUBLISHED
- ascelerate events info <bundle-id> <reference-name-or-id>
- # Create, update, delete (events are referenced by name or ID)
- ascelerate events create <bundle-id> --reference-name "summer-sale" --badge SPECIAL_EVENT --purpose ATTRACT_NEW_USERS --priority HIGH
- ascelerate events create <bundle-id> --reference-name "launch" --territories USA,GBR --publish-start 2026-07-01 --event-start 2026-07-05 --event-end 2026-07-12
- ascelerate events update <bundle-id> summer-sale --priority NORMAL --badge NONE
- ascelerate events delete <bundle-id> summer-sale
- # Localizations (name, short description, long description per locale)
- ascelerate events localizations view <bundle-id> summer-sale
- ascelerate events localizations export <bundle-id> summer-sale
- ascelerate events localizations import <bundle-id> summer-sale --file event-locales.json
- # Media — event card / details page screenshots and video clips
- ascelerate events media list <bundle-id> summer-sale
- ascelerate events media upload <bundle-id> summer-sale --locale en-US --asset-type EVENT_CARD card.png
- ascelerate events media upload <bundle-id> summer-sale --locale en-US --asset-type EVENT_DETAILS_PAGE clip.mp4 --preview-frame 00:00:03:00
- ascelerate events media delete <bundle-id> summer-sale <media-id>
- ```
- Badges: `LIVE_EVENT`, `PREMIERE`, `CHALLENGE`, `COMPETITION`, `NEW_SEASON`, `MAJOR_UPDATE`, `SPECIAL_EVENT`. Purposes: `APPROPRIATE_FOR_ALL_USERS`, `ATTRACT_NEW_USERS`, `KEEP_ACTIVE_USERS_INFORMED`, `BRING_BACK_LAPSED_USERS`. Schedule dates accept ISO8601 or `yyyy-MM-dd`. Asset types: `EVENT_CARD`, `EVENT_DETAILS_PAGE`. Localization locales must match the app's configured locales (e.g. `tr`, not `tr-TR`).
- ### Custom Product Pages
- ```bash
- # List and inspect
- ascelerate product-pages list <bundle-id>
- ascelerate product-pages info <bundle-id> <name-or-id>
- # Create — the API requires a first version + localization, so --locale is required
- ascelerate product-pages create <bundle-id> --name "Summer Campaign" --locale en-US --promotional-text "Limited-time offer"
- # Rename or toggle App Store visibility
- ascelerate product-pages update <bundle-id> "Summer Campaign" --name "Summer 2026" --visible false
- ascelerate product-pages delete <bundle-id> "Summer Campaign"
- # Localizations (promotional text per locale)
- ascelerate product-pages localizations view <bundle-id> "Summer 2026"
- ascelerate product-pages localizations export <bundle-id> "Summer 2026"
- ascelerate product-pages localizations import <bundle-id> "Summer 2026" --file page-locales.json
- # Screenshots & app previews (sets created on first upload)
- ascelerate product-pages media list <bundle-id> "Summer 2026"
- ascelerate product-pages media upload <bundle-id> "Summer 2026" --locale en-US --display-type APP_IPHONE_67 screenshot.png
- ascelerate product-pages media upload <bundle-id> "Summer 2026" --locale en-US --preview-type APP_IPHONE_67 preview.mp4 --preview-frame 00:00:03:00
- ascelerate product-pages media delete <bundle-id> "Summer 2026" <media-id>
- ```
- Pages are referenced by name or ID. Each page's shareable App Store URL (with its `ppid`) appears in `list` and `info`.
- ### Product Page Optimization
- A/B test screenshots, previews and app icons against the original product page:
- ```bash
- ascelerate experiments <bundle-id> # list tests
- ascelerate experiments create <bundle-id> --name "Screenshot order" --traffic 50 --treatment "Map first"
- ascelerate experiments media upload <bundle-id> "Screenshot order" "Map first" --locale en-US --display-type APP_IPHONE_67 01.png
- ascelerate experiments info <bundle-id> "Screenshot order" # treatments, locales and media
- ascelerate experiments submit <bundle-id> "Screenshot order" # App Review
- ascelerate experiments start <bundle-id> "Screenshot order" # once approved
- ascelerate experiments stop <bundle-id> "Screenshot order"
- ```
- `treatments add/update/delete/remove-locale` manage treatments (`--app-icon` tests an alternate icon from the live build); `media list/delete` manage their media. Tests and treatments are referenced by name or ID.
- ### Reports
- Download Sales & Trends, Financial, and App Analytics reports. Sales/Finance reports come back as Apple's gzipped TSV — ascelerate decompresses and summarizes them (or saves the raw file with `--output`/`--raw`).
- ```bash
- # Sales & Trends — units/downloads, proceeds, IAP/subscription activity
- ascelerate reports sales # most recent day, all apps
- ascelerate reports sales --frequency WEEKLY
- ascelerate reports sales --frequency MONTHLY --date 2026-05
- ascelerate reports sales --frequency YEARLY --date 2025 --bundle-id com.example.App
- ascelerate reports sales --frequency DAILY --date 2026-06-20 --output sales.tsv
- # Financial report — units + partner proceeds for a fiscal period, by region
- ascelerate reports finance --date 2026-05 --region US
- ascelerate reports finance --date 2026-05 --region US --type FINANCE_DETAIL --output finance.tsv
- # App Analytics — downloads, impressions, sessions (async: creates/reuses a report request)
- ascelerate reports analytics <bundle-id>
- ascelerate reports analytics <bundle-id> --category APP_USAGE --granularity WEEKLY
- ```
- - `reports sales` / `reports finance` need a **vendor number** (App Store Connect → Payments and Financial Reports). Save it with `configure` or pass `--vendor-number`.
- - The sales summary groups units by app and **product type identifier**, distinguishing first-time downloads (`1*`/`3*`) from updates (`7*`) and in-app purchases (`IA*`). Use `--raw` for the full TSV.
- - Apple generates analytics reports asynchronously — a freshly created snapshot isn't ready immediately; re-run the command after a few minutes to download the segments.
- - The API does not expose aggregate rating counts or the star-rating average — only individual reviews (see Customer Reviews).
- ### Diagnostics
- What Xcode's Organizer shows, from users' devices: a build's hangs, slow launches and disk writes with their call stacks, and performance and power metrics across versions (the build on the App Store unless `--build`):
- ```bash
- ascelerate diagnostics <bundle-id> # signatures by type, heaviest first
- ascelerate diagnostics logs <signature-id> # sampled events with call stacks (▶ blamed frame)
- ascelerate diagnostics metrics <bundle-id> [--type launch,hang] [--all] # per version, 50th/90th percentile; regressions first
- ```
- ### Apple Ads
- Manage Apple Ads (formerly Search Ads) campaigns through the Apple Ads Platform API: performance reports, keywords and negative keywords, bids and budgets, plus Apple's keyword research data. Apps are matched with App Store Connect, so `--app` takes the same bundle IDs and aliases as every other command.
- ```bash
- # One-time setup: creates the key pair, prints the public key to paste into
- # Apple Ads → Account Settings → API, then asks for clientId/teamId/keyId
- ascelerate ads configure
- # Performance (--days N or --from/--to; --app, --campaign; --json)
- ascelerate ads reports campaigns --days 30
- ascelerate ads reports campaigns --campaign "MyApp US" --by device # also age, gender, country, region, city
- ascelerate ads reports keywords --campaign "MyApp US" # with Apple's suggested bid
- ascelerate ads reports search-terms --app myapp # what people searched, which keyword matched
- # Campaigns, keywords, negatives (writes confirm first; --dry-run shows the requests)
- ascelerate ads campaigns list
- ascelerate ads campaigns pause "MyApp US"
- ascelerate ads campaigns budget "MyApp US" --daily 120
- ascelerate ads campaigns create --like "MyApp US" --name "MyApp US Max Conv" --max-conversions --bid 2.50 --daily 25 # paused, with its automated ad group
- ascelerate ads keywords add --campaign "MyApp US" --match exact --bid 1.50 "qr scanner" "barcode reader"
- ascelerate ads keywords bid --campaign "MyApp US" --bid 1.25 "qr scanner"
- ascelerate ads negatives add --campaign "MyApp US" "free wifi"
- ascelerate ads adgroups create --campaign "MyApp US" --name "Exact" --search-match off # copy of the existing group, paused
- ascelerate ads keywords copy --campaign "MyApp US" --from "US Ad Group" --to "Exact"
- ascelerate ads reports adgroups --campaign "MyApp US"
- # What to change: search terms to add as keywords, give their own bid, or exclude
- ascelerate ads opportunities --app myapp
- ascelerate ads recommendations apply <id>
- ascelerate ads campaigns target-cpa --app myapp --country US # Apple's suggested Max Conversions target
- ascelerate ads history --app myapp --days 7 # who changed what, old → new
- # Ad variations: send an ad group's taps to a custom product page (made in App Store Connect)
- ascelerate ads product-pages --app myapp
- ascelerate ads ads create --campaign "MyApp US" --ad-group "Scanner" --product-page "Scanner Page" --enabled
- ascelerate ads reports ads --campaign "MyApp US"
- # Keyword research and market insights
- ascelerate ads keywords suggest --app myapp --seed "qr code" --country US
- ascelerate ads keywords popularity --app myapp --country US --term "qr code" "qr scanner"
- ascelerate ads insights impression-share --app myapp --country US
- ascelerate ads recommendations
- ```
- - Apple Ads uses its own credentials: an Apple Ads user with an API role (Account Settings → User Management). `ads configure` stores them in the `ads` section of `~/.ascelerate/config.json`.
- - Reports show both conversion rates: **CR (Tap)** counts installs after a tap; **CR (Total)** adds view-through installs (people who saw the ad and installed without tapping), so it can exceed 100%.
- - Search terms Apple withholds for privacy show as "(low volume)"; keyword suggestions are only relevant with `--seed`.
- - Apple knows age, gender and location (below country) only for users who allowed Personalized Ads, so those breakdowns come back almost entirely as "Unknown"; device is complete.
- ### Rate Limit
- Check your current API usage against the rolling hourly quota:
- ```bash
- ascelerate rate-limit
- ```
- ```
- Hourly limit: 3600 requests (rolling window)
- Used: 57
- Remaining: 3543 (98%)
- ```
- ### Workflows
- Chain multiple commands into a single automated run with a workflow file:
- ```bash
- ascelerate run-workflow release.txt
- ascelerate run-workflow release.txt --yes # skip all prompts (CI/CD)
- ascelerate run-workflow # interactively select from .workflow/.txt files
- ascelerate run-workflow release.txt --check # every step parses (--json: each step's line and error); nothing runs
- ascelerate run-workflow release.txt --json-events # JSON events on stdout (steps, outcomes, prompts answered on stdin); output on stderr
- ```
- A workflow file is a plain text file with one command per line (without the `ascelerate` prefix). Lines starting with `#` are comments, blank lines are ignored. Both `.workflow` and `.txt` extensions are supported.
- **Example** -- `release.txt` for submitting version 2.1.0 of a sample app:
- ```
- # Release workflow for MyApp v2.1.0
- # Create the new version on App Store Connect
- apps create-version com.example.MyApp 2.1.0
- # Build, validate, and upload
- builds archive --scheme MyApp
- builds validate --latest --bundle-id com.example.MyApp
- builds upload --latest --bundle-id com.example.MyApp
- # Wait for the build to finish processing
- builds await-processing com.example.MyApp
- # Update localizations and attach the build
- apps localizations import com.example.MyApp --file localizations.json
- apps build attach-latest com.example.MyApp
- # Submit for review
- apps review submit com.example.MyApp
- ```
- Without `--yes`, the workflow asks for confirmation before starting, and individual commands still prompt where they normally would (e.g., before submitting for review). With `--yes`, all prompts are skipped for fully unattended execution.
- ### Automation
- Most commands that prompt for confirmation support `--yes` / `-y` to skip prompts, making them suitable for CI/CD pipelines and scripts. When using `--yes` with provisioning commands, all required arguments must be provided explicitly (interactive mode is disabled):
- ```bash
- ascelerate apps build attach-latest <bundle-id> --yes
- ascelerate apps review submit <bundle-id> --yes
- ```
- On universal-purchase apps, also pass `--platform` so unattended runs never hit the interactive platform-disambiguation prompt.
- ### Dry run
- Add `--dry-run` to try a command or a whole workflow without changing anything on App Store Connect. The option works anywhere on the command line, and setting `ASCELERATE_DRY_RUN=1` does the same. Reads go out as usual, so lookups and checks run against your real data, but every write is stopped before it is sent: ascelerate prints its method, path, and JSON body to stderr and reports that the request was not sent.
- ```bash
- ascelerate apps localizations import <bundle-id> --file localizations.json --yes --dry-run
- ascelerate run-workflow release.txt --yes --dry-run
- ASCELERATE_DRY_RUN=1 ascelerate run-workflow release.txt --yes # same, e.g. for a whole CI job
- ```
- A command stops at its first blocked write, or reports each blocked request as failed where it works through items one by one. In `run-workflow`, a step whose writes were blocked doesn't stop the workflow, so a single run shows every step's writes (in a workflow file, `--dry-run` on a single step applies only to that step); a step that relies on something an earlier step would have created (a new version, an uploaded build) can still fail. `builds upload` skips the upload; `builds archive` and `builds validate` still run, since they don't change anything on App Store Connect.
- ### API rate limit
- App Store Connect allows 3,600 API requests per hour for your key, counted over a rolling hour. When a long command uses them up, ascelerate waits until App Store Connect allows requests again, shows when it will continue, and carries on (Ctrl-C stops it). To fail instead, e.g. in CI, set `ASCELERATE_MAX_RATE_LIMIT_WAIT` to the most seconds a run may wait in total (`0` fails at the first rate-limited request). `ascelerate rate-limit` shows what's left and never waits.
- ### Upload chunks
- App Store Connect takes uploaded files (screenshots, previews, builds with `builds upload --api`, and other media) in chunks. ascelerate sends them one at a time, which leaves bandwidth for everything else on the connection. On a fast connection with a long round trip to Apple's storage, sending several at once can finish sooner: set `ASCELERATE_PARALLEL_CHUNKS` to the number of chunks to send at the same time.
- ```bash
- ASCELERATE_PARALLEL_CHUNKS=4 ascelerate apps media upload <bundle-id> media/
- ```
- ### Version
- ```bash
- ascelerate version # Prints version number
- ascelerate --version # Same as above
- ascelerate -v # Same as above
- ```
- ## Acknowledgments
- Versions up to 0.21 were built on top of [asc-swift](https://github.com/aaronsky/asc-swift) by Aaron Sky. Thank you!
- *"A Swift Client, App Store Connect"* — [@validatedev](https://x.com/validatedev/status/2026613415012118674)
- The design generator instructions (`ascelerate screenshot setup-prompt --design`, formerly the app-store-screenshots skill) are based on [ParthJadhav/app-store-screenshots](https://github.com/ParthJadhav/app-store-screenshots), significantly rewritten with device bezel framing, iPad support, localization, and ascelerate-compatible export.
- Developed with [Claude Code](https://claude.ai/code).
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.