Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/keremerkan--ascelerate/badge.svg)](/listings/keremerkan--ascelerate)

HTML

<a href="/listings/keremerkan--ascelerate"><img src="/api/listings/keremerkan--ascelerate/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

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.

  1. <p align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="website/static/img/icon-dark.png">
  4. <img src="website/static/img/icon.png" width="128" alt="ascelerate icon">
  5. </picture>
  6. </p>
  7. # ascelerate — A Swift CLI for App Store Connect
  8. 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).
  9. > **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.
  10. > **Full documentation:** [ascelerate.dev](https://ascelerate.dev)
  11. > **Prefer an app?** Ascelerate brings App Store Connect to Mac, iPhone and iPad, built on ascelerate. See [Ascelerate: the app](#ascelerate-the-app).
  12. ## Ascelerate: the app
  13. [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.
  14. - **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.
  15. - **TestFlight:** builds, groups and testers, What to Test, beta review and tester feedback.
  16. - **In-app purchases and subscriptions:** prices in every territory, introductory and promotional offers, offer codes and promoted purchases.
  17. - **Growth:** in-app events, custom product pages, product page optimization tests, featuring nominations, and ratings and reviews with your responses.
  18. - **Certificates, Identifiers & Profiles:** certificates, bundle IDs and their capabilities, devices and provisioning profiles.
  19. - **Reports:** Sales and Trends and App Analytics, and an overview of what needs your attention across your apps.
  20. - **Apple Ads:** campaigns, ad groups, keywords and their performance.
  21. - **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.
  22. 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.
  23. ## Requirements
  24. - macOS 15+
  25. - Swift 6.2+ (only for building from source)
  26. ## Installation
  27. ### Homebrew
  28. ```bash
  29. brew install ascelerate
  30. ```
  31. 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.
  32. ### Install script
  33. ```bash
  34. curl -fsSL https://raw.githubusercontent.com/keremerkan/ascelerate/main/install.sh | bash
  35. ```
  36. 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`.
  37. ### Download manually
  38. Download the latest release from [GitHub Releases](https://github.com/keremerkan/ascelerate/releases):
  39. ```bash
  40. curl -L https://github.com/keremerkan/ascelerate/releases/latest/download/ascelerate-macos-arm64.tar.gz -o ascelerate.tar.gz
  41. tar xzf ascelerate.tar.gz
  42. sudo mkdir -p /usr/local/bin
  43. sudo mv ascelerate /usr/local/bin/
  44. ```
  45. 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.
  46. > **Note:** Pre-built binaries are provided for Apple Silicon (arm64) only. Intel Mac users should build from source.
  47. ### Build from source
  48. ```bash
  49. git clone https://github.com/keremerkan/ascelerate.git
  50. cd ascelerate
  51. swift build -c release
  52. strip .build/release/ascelerate
  53. cp .build/release/ascelerate /usr/local/bin/
  54. ```
  55. > **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.
  56. ### Shell completions
  57. Set up tab completion for subcommands, options, and flags (supports zsh and bash):
  58. ```bash
  59. ascelerate install-completions
  60. ```
  61. This detects your shell and configures everything automatically. Restart your shell or open a new tab to activate.
  62. ### AI coding skill
  63. 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.
  64. **Via the binary** (detects your installed agents):
  65. ```bash
  66. ascelerate install-skill # install/update for every detected agent
  67. ascelerate install-skill --all # include all supported agents (e.g. Copilot)
  68. ```
  69. 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.
  70. **Via npx** (any AI coding agent):
  71. ```bash
  72. npx ascelerate-skill
  73. ```
  74. 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.
  75. ## Setup
  76. ### 1. Create an API Key
  77. 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.
  78. ### 2. Configure
  79. ```bash
  80. ascelerate configure
  81. ```
  82. 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).
  83. ### A key for one run
  84. 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:
  85. ```bash
  86. export ASCELERATE_KEY_ID=KEY_ID
  87. export ASCELERATE_ISSUER_ID=ISSUER_ID
  88. export ASCELERATE_PRIVATE_KEY_PATH=~/keys/AuthKey_KEY_ID.p8
  89. ascelerate apps list
  90. ```
  91. `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.
  92. ## Usage
  93. ### Aliases
  94. Instead of typing full bundle IDs every time, you can create short aliases:
  95. ```bash
  96. # Add an alias (interactive app picker)
  97. ascelerate alias add myapp
  98. # Now use the alias anywhere you'd use a bundle ID
  99. ascelerate apps info myapp
  100. ascelerate apps versions myapp
  101. ascelerate apps localizations view myapp
  102. # List all aliases
  103. ascelerate alias list
  104. # Remove an alias
  105. ascelerate alias remove myapp
  106. ```
  107. 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.
  108. ### JSON output
  109. Read commands support `--json` for machine-readable output, ready for `jq`, scripts, and AI agents:
  110. ```bash
  111. ascelerate apps list --json
  112. ascelerate apps info <bundle-id> --json
  113. ascelerate apps versions <bundle-id> --json
  114. ascelerate apps review preflight <bundle-id> --json
  115. ascelerate apps review status <bundle-id> --json
  116. ascelerate builds list --bundle-id <bundle-id> --json
  117. ascelerate testflight builds <bundle-id> --json
  118. ascelerate testflight status <bundle-id> --json
  119. ascelerate reviews list <bundle-id> --json
  120. ascelerate reviews info <review-id> --json
  121. ascelerate iap list <bundle-id> --json
  122. ascelerate iap info <bundle-id> <product-id> --json
  123. ascelerate iap pricing show <bundle-id> <product-id> --json
  124. ascelerate sub groups <bundle-id> --json
  125. ascelerate sub list <bundle-id> --json
  126. ascelerate sub info <bundle-id> <product-id> --json
  127. ascelerate sub pricing show <bundle-id> <product-id> --json
  128. ascelerate rate-limit --json
  129. ```
  130. 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.
  131. ### Apps
  132. ```bash
  133. # List all apps
  134. ascelerate apps list
  135. # Show app details
  136. ascelerate apps info <bundle-id>
  137. # List App Store versions
  138. ascelerate apps versions <bundle-id>
  139. # Create a new version
  140. ascelerate apps create-version <bundle-id> <version-string>
  141. ascelerate apps create-version <bundle-id> 2.1.0 --platform ios --release-type manual
  142. # View or update the copyright notice
  143. ascelerate apps copyright <bundle-id>
  144. ascelerate apps copyright <bundle-id> --set "2026 Your Name" --version 2.1.0 --platform macos
  145. # Check review submission status
  146. ascelerate apps review status <bundle-id>
  147. ascelerate apps review status <bundle-id> --version 2.1.0
  148. # Submit for review
  149. ascelerate apps review submit <bundle-id>
  150. ascelerate apps review submit <bundle-id> --version 2.1.0
  151. ascelerate apps review submit <bundle-id> --platform macos
  152. # Resolve rejected review items (after fixing issues and replying in Resolution Center)
  153. ascelerate apps review resolve-issues <bundle-id>
  154. # Cancel an active review submission
  155. ascelerate apps review cancel-submission <bundle-id>
  156. # View or update App Review Information (contact, demo account, notes)
  157. ascelerate apps review info <bundle-id>
  158. 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…"
  159. # App Review attachment files (demo videos, docs, etc.)
  160. ascelerate apps review attachment list <bundle-id>
  161. ascelerate apps review attachment upload <bundle-id> demo.mp4
  162. ascelerate apps review attachment delete <attachment-id>
  163. ```
  164. 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`.
  165. #### Pre-submission preflight checks
  166. Before submitting for review, run `preflight` to verify that all required fields are filled in across every locale:
  167. ```bash
  168. # Check the latest editable version
  169. ascelerate apps review preflight <bundle-id>
  170. # Check a specific version
  171. ascelerate apps review preflight <bundle-id> --version 2.1.0
  172. ```
  173. 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:
  174. ```
  175. Preflight checks for MyApp v2.1.0 (Prepare for Submission)
  176. Check Status
  177. ──────────────────────────────────────────────────────────────────
  178. Version state ✓ Prepare for Submission
  179. Build attached ✓ Build 42
  180. Copyright ✓ 2026 Your Name
  181. Review contact ✓ Jane Doe, jane@example.com
  182. Sign-in ✓ Not required
  183. Category ✓ Productivity
  184. Content rights ✓ Does Not Use Third Party Content
  185. Price ✓ Set
  186. Availability ✓ 175 territories
  187. en-US (English (United States))
  188. App info ✓ All fields filled
  189. Localizations ✓ All fields filled
  190. Screenshots ✓ 2 sets, 10 screenshots
  191. de-DE (German (Germany))
  192. App info ✓ All fields filled
  193. Localizations ✗ Missing: Keywords, What's New
  194. Screenshots ✓ None (uses en-US's)
  195. ──────────────────────────────────────────────────────────────────
  196. Result: 14 passed, 1 failed
  197. ```
  198. 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.
  199. 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.
  200. ### Build Management
  201. ```bash
  202. # Interactively select and attach a build to a version
  203. ascelerate apps build attach <bundle-id>
  204. ascelerate apps build attach <bundle-id> --version 2.1.0
  205. # Attach the most recent build automatically
  206. ascelerate apps build attach-latest <bundle-id>
  207. ascelerate apps build attach-latest <bundle-id> --platform macos
  208. # Remove the attached build from a version
  209. ascelerate apps build detach <bundle-id>
  210. ```
  211. 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.
  212. ### Phased Release
  213. ```bash
  214. # View phased release status
  215. ascelerate apps phased-release <bundle-id>
  216. # Enable phased release (starts inactive, activates when version goes live)
  217. ascelerate apps phased-release <bundle-id> --enable
  218. # Pause, resume, or complete a phased release
  219. ascelerate apps phased-release <bundle-id> --pause
  220. ascelerate apps phased-release <bundle-id> --resume
  221. ascelerate apps phased-release <bundle-id> --complete
  222. # Remove phased release entirely
  223. ascelerate apps phased-release <bundle-id> --disable
  224. ```
  225. ### Manual Release
  226. When a version's release option is set to manual, the approved version sits in Pending Developer Release until you release it:
  227. ```bash
  228. # Release the version that is pending developer release
  229. ascelerate apps release <bundle-id>
  230. # Target a specific version or platform
  231. ascelerate apps release <bundle-id> --version 2.1.0 --platform macos
  232. ```
  233. ### Age Rating
  234. ```bash
  235. # View age rating declaration
  236. ascelerate apps app-info age-rating <bundle-id>
  237. # Export age rating to JSON
  238. ascelerate apps app-info age-rating export <bundle-id>
  239. # Update age ratings from a JSON file
  240. ascelerate apps app-info age-rating import <bundle-id> --file age-rating.json
  241. ```
  242. The JSON file uses the same field names as the API. Only fields present in the file are updated:
  243. ```json
  244. {
  245. "isAdvertising": false,
  246. "isUserGeneratedContent": true,
  247. "violenceCartoonOrFantasy": "INFREQUENT_OR_MILD",
  248. "alcoholTobaccoOrDrugUseOrReferences": "NONE"
  249. }
  250. ```
  251. Intensity fields accept: `NONE`, `INFREQUENT_OR_MILD`, `FREQUENT_OR_INTENSE`. Boolean fields accept `true`/`false`.
  252. ### Routing App Coverage
  253. ```bash
  254. # View current routing coverage status
  255. ascelerate apps routing-coverage <bundle-id>
  256. # Upload a .geojson file
  257. ascelerate apps routing-coverage <bundle-id> --file coverage.geojson
  258. ```
  259. ### Localizations
  260. ```bash
  261. # View localizations (latest version by default)
  262. ascelerate apps localizations view <bundle-id>
  263. ascelerate apps localizations view <bundle-id> --version 2.1.0 --locale en-US
  264. # Export localizations to JSON
  265. ascelerate apps localizations export <bundle-id>
  266. ascelerate apps localizations export <bundle-id> --version 2.1.0 --output my-localizations.json
  267. # Update a single locale
  268. ascelerate apps localizations update <bundle-id> --whats-new "Bug fixes" --locale en-US
  269. # Bulk update from JSON file
  270. ascelerate apps localizations import <bundle-id> --file localizations.json
  271. ```
  272. The JSON format for export and bulk update:
  273. ```json
  274. {
  275. "en-US": {
  276. "description": "My app description.\n\nSecond paragraph.",
  277. "whatsNew": "- Bug fixes\n- New dark mode",
  278. "keywords": "productivity,tools,utility",
  279. "promotionalText": "Try our new features!",
  280. "marketingURL": "https://example.com",
  281. "supportURL": "https://example.com/support"
  282. },
  283. "de-DE": {
  284. "whatsNew": "- Fehlerbehebungen\n- Neuer Dunkelmodus"
  285. }
  286. }
  287. ```
  288. Only fields present in the JSON are updated -- omitted fields are left unchanged.
  289. ### Screenshots & App Previews
  290. ```bash
  291. # Download all screenshots and preview videos
  292. ascelerate apps media download <bundle-id>
  293. ascelerate apps media download <bundle-id> --folder my-media/ --version 2.1.0
  294. ascelerate apps media download <bundle-id> --locale en-US,tr
  295. # Upload screenshots and preview videos from a folder
  296. ascelerate apps media upload <bundle-id> media/
  297. # Upload from an archive (zip, tar, tar.gz supported)
  298. ascelerate apps media upload <bundle-id> screenshots.zip
  299. # Upload to a specific version
  300. ascelerate apps media upload <bundle-id> media/ --version 2.1.0
  301. # Replace existing media in matching sets before uploading
  302. ascelerate apps media upload <bundle-id> media/ --replace
  303. # Interactive mode: pick a folder or archive from the current directory
  304. ascelerate apps media upload <bundle-id>
  305. ```
  306. 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.
  307. Organize your media folder with locale and display type subfolders:
  308. ```
  309. media/
  310. ├── en-US/
  311. │ ├── APP_IPHONE_67/
  312. │ │ ├── 01_home.png
  313. │ │ ├── 02_settings.png
  314. │ │ └── preview.mp4
  315. │ └── APP_IPAD_PRO_3GEN_129/
  316. │ └── 01_home.png
  317. └── de-DE/
  318. └── APP_IPHONE_67/
  319. ├── 01_home.png
  320. └── 02_settings.png
  321. ```
  322. - **Level 1:** Locale (e.g. `en-US`, `de-DE`, `ja`)
  323. - **Level 2:** Display type folder name (see table below)
  324. - **Level 3:** Media files -- images (`.png`, `.jpg`, `.jpeg`) become screenshots, videos (`.mp4`, `.mov`) become app previews
  325. - Files are uploaded in alphabetical order by filename
  326. - Unsupported files are skipped with a warning
  327. #### Display types
  328. 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.
  329. | Folder name | Device | Screenshots | Previews |
  330. |---|---|---|---|
  331. | `APP_IPHONE_67` | iPhone 6.7" (iPhone 17 Pro Max, 16 Pro Max, 15 Pro Max) | **Required** | Yes |
  332. | `APP_IPAD_PRO_3GEN_129` | iPad Pro 12.9" (3rd gen+) | **Required** | Yes |
  333. <details>
  334. <summary>All optional display types</summary>
  335. | Folder name | Device | Screenshots | Previews |
  336. |---|---|---|---|
  337. | `APP_IPHONE_61` | iPhone 6.1" (iPhone 17 Pro, 16 Pro, 15 Pro) | Yes | Yes |
  338. | `APP_IPHONE_65` | iPhone 6.5" (iPhone 11 Pro Max, XS Max) | Yes | Yes |
  339. | `APP_IPHONE_58` | iPhone 5.8" (iPhone 11 Pro, X, XS) | Yes | Yes |
  340. | `APP_IPHONE_55` | iPhone 5.5" (iPhone 8 Plus, 7 Plus, 6s Plus) | Yes | Yes |
  341. | `APP_IPHONE_47` | iPhone 4.7" (iPhone SE 3rd gen, 8, 7, 6s) | Yes | Yes |
  342. | `APP_IPHONE_40` | iPhone 4" (iPhone SE 1st gen, 5s, 5c) | Yes | Yes |
  343. | `APP_IPHONE_35` | iPhone 3.5" (iPhone 4s and earlier) | Yes | Yes |
  344. | `APP_IPHONE_DUO` | iPhone Duo (uploaded through the asset library, see below) | Yes | No |
  345. | `PRODUCT_PAGE_HEADER` | Product page header image (asset library, see below) | Yes | No |
  346. | `APP_STORE_SEARCH_RESULTS` | App Store search results image (asset library, see below) | Yes | No |
  347. | `APP_IPAD_PRO_3GEN_11` | iPad Pro 11" | Yes | Yes |
  348. | `APP_IPAD_PRO_129` | iPad Pro 12.9" (1st/2nd gen) | Yes | Yes |
  349. | `APP_IPAD_105` | iPad 10.5" (iPad Air 3rd gen, iPad Pro 10.5") | Yes | Yes |
  350. | `APP_IPAD_97` | iPad 9.7" (iPad 6th gen and earlier) | Yes | Yes |
  351. | `APP_DESKTOP` | Mac | Yes | Yes |
  352. | `APP_APPLE_TV` | Apple TV | Yes | Yes |
  353. | `APP_APPLE_VISION_PRO` | Apple Vision Pro | Yes | Yes |
  354. | `APP_WATCH_ULTRA` | Apple Watch Ultra | Yes | No |
  355. | `APP_WATCH_SERIES_10` | Apple Watch Series 10 | Yes | No |
  356. | `APP_WATCH_SERIES_7` | Apple Watch Series 7 | Yes | No |
  357. | `APP_WATCH_SERIES_4` | Apple Watch Series 4 | Yes | No |
  358. | `APP_WATCH_SERIES_3` | Apple Watch Series 3 | Yes | No |
  359. | `IMESSAGE_APP_IPHONE_67` | iMessage iPhone 6.7" | Yes | No |
  360. | `IMESSAGE_APP_IPHONE_61` | iMessage iPhone 6.1" | Yes | No |
  361. | `IMESSAGE_APP_IPHONE_65` | iMessage iPhone 6.5" | Yes | No |
  362. | `IMESSAGE_APP_IPHONE_58` | iMessage iPhone 5.8" | Yes | No |
  363. | `IMESSAGE_APP_IPHONE_55` | iMessage iPhone 5.5" | Yes | No |
  364. | `IMESSAGE_APP_IPHONE_47` | iMessage iPhone 4.7" | Yes | No |
  365. | `IMESSAGE_APP_IPHONE_40` | iMessage iPhone 4" | Yes | No |
  366. | `IMESSAGE_APP_IPAD_PRO_3GEN_129` | iMessage iPad Pro 12.9" (3rd gen+) | Yes | No |
  367. | `IMESSAGE_APP_IPAD_PRO_3GEN_11` | iMessage iPad Pro 11" | Yes | No |
  368. | `IMESSAGE_APP_IPAD_PRO_129` | iMessage iPad Pro 12.9" (1st/2nd gen) | Yes | No |
  369. | `IMESSAGE_APP_IPAD_105` | iMessage iPad 10.5" | Yes | No |
  370. | `IMESSAGE_APP_IPAD_97` | iMessage iPad 9.7" | Yes | No |
  371. </details>
  372. > **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.
  373. >
  374. > 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.
  375. >
  376. > `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.
  377. >
  378. > `media download` saves files in this same folder structure (defaults to `<bundle-id>-media/`), so you can download, edit, and re-upload.
  379. #### Designing App Store images
  380. `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:
  381. ```
  382. export/en-US/APP_IPHONE_67/01_hero.png
  383. export/en-US/APP_IPAD_PRO_3GEN_129/01_hero.png
  384. export/de-DE/APP_IPHONE_67/01_hero.png
  385. ```
  386. ```bash
  387. ascelerate apps media upload <bundle-id> export --platform ios --replace
  388. ```
  389. 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.
  390. #### Verify and retry stuck media
  391. 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:
  392. ```bash
  393. # Check status of all screenshots and previews
  394. ascelerate apps media verify <bundle-id>
  395. # Check a specific version
  396. ascelerate apps media verify <bundle-id> --version 2.1.0
  397. # Retry stuck items using local files from the media folder
  398. ascelerate apps media verify <bundle-id> media/
  399. ```
  400. 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.
  401. 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.
  402. #### Prune stale sets
  403. `--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:
  404. ```bash
  405. ascelerate apps media prune <bundle-id> media/
  406. ascelerate apps media prune <bundle-id> media/ --version 2.1.0 --platform ios
  407. ```
  408. Locales that have no local folder at all are skipped entirely — the command only prunes within locales the folder actually manages.
  409. #### Remove asset library images
  410. `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:
  411. ```bash
  412. ascelerate apps media remove <bundle-id> PRODUCT_PAGE_HEADER --locale en-US
  413. ascelerate apps media remove <bundle-id> APP_IPHONE_DUO --locale en-US,tr --version 2.1.0
  414. ```
  415. #### Clean up the asset library
  416. 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:
  417. ```bash
  418. ascelerate apps media library <bundle-id>
  419. ascelerate apps media library <bundle-id> --delete-unused
  420. ascelerate apps media library <bundle-id> --only APP_IPHONE_DUO --delete-unused
  421. ```
  422. `--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.
  423. Images that went through App Review are never deleted, and each one is checked again right before it is deleted.
  424. ### Capturing Screenshots
  425. Capture App Store screenshots directly from iOS/iPadOS simulators using UI tests. Replaces [fastlane snapshot](https://docs.fastlane.tools/actions/snapshot/).
  426. ```bash
  427. # Let an AI coding agent set it up: UI tests, helper, screenshot mode with demo content, configuration
  428. ascelerate screenshot setup-prompt --copy # Copies instructions to paste into the agent (--design: a design generator)
  429. # Or by hand: generate config and helper files
  430. ascelerate screenshot init # Creates ascelerate/screenshot.yml and ascelerate/ScreenshotHelper.swift
  431. # Capture screenshots
  432. ascelerate screenshot run
  433. ascelerate screenshot run -l en-US,tr-TR # Only capture a subset of configured languages
  434. ascelerate screenshot run --json-events # Progress as JSON Lines on stdout for other tools
  435. ascelerate screenshot frame # Frame screenshots with device bezels
  436. ascelerate screenshot doctor [--json] # Check config and environment for problems
  437. ```
  438. 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).
  439. Add `ScreenshotHelper.swift` to your UITest target, then call `setupScreenshots(app)` in `setUp()` and `screenshot("name")` to capture:
  440. ```swift
  441. override func setUp() {
  442. setupScreenshots(app)
  443. app.launch()
  444. }
  445. func testScreenshots() {
  446. screenshot("01-home")
  447. app.buttons["Settings"].tap()
  448. screenshot("02-settings")
  449. }
  450. ```
  451. 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.
  452. Configure via `ascelerate/screenshot.yml`:
  453. ```yaml
  454. # workspace: MyApp.xcworkspace
  455. project: MyApp.xcodeproj
  456. scheme: AppUITests
  457. devices:
  458. - simulator: iPhone 17 Pro Max
  459. # frameDevice: true
  460. # deviceBezel: ./bezels/iPhone 17 Pro Max.png
  461. - simulator: iPad Pro 13-inch (M5)
  462. # frameDevice: true
  463. # deviceBezel: ./bezels/iPad Pro 13-inch (M5).png
  464. languages:
  465. - en-US
  466. - de-DE
  467. outputDirectory: ./screenshots
  468. # framedOutputDirectory: ./screenshots/framed
  469. clearPreviousScreenshots: true
  470. localizeSimulator: true
  471. overrideStatusBar: true
  472. # darkMode: false
  473. # disableAnimations: false
  474. # waitAfterBoot: 0
  475. # configuration: Debug
  476. # testplan: MyTestPlan
  477. # numberOfRetries: 0 # Retry failed languages (erase + reboot simulator)
  478. # stopAfterFirstError: false
  479. # reinstallApp: false
  480. # disableAssetDownloads: false # Disable mobileassetd (no Siri/keyboard/ML asset downloads; also blocks on-device ML assets)
  481. # xcargs: -maximum-parallel-testing-workers 2
  482. ```
  483. Features:
  484. - Builds once, then runs tests across all languages
  485. - iPhone and iPad run concurrently per language
  486. - Status bar override (9:41, full bars, no carrier)
  487. - Simulator localization per language
  488. - Dark mode support
  489. - Animation disabling for reliable captures
  490. - Automatic retries for failed languages (erases simulator, re-localizes, reboots, and reruns)
  491. - Errors skip and continue, with summary table and error logs saved to output
  492. - Helper version tracking with update warnings
  493. - Device bezel framing with [Apple Product Bezels](https://developer.apple.com/design/resources/#product-bezels) (download required)
  494. - Config validation via `doctor` subcommand
  495. - `create-helper` available separately but also run automatically by `init`
  496. Output structure:
  497. ```
  498. screenshots/
  499. ├── en-US/
  500. │ ├── iPhone-01-home.png
  501. │ └── iPad-01-home.png
  502. └── de-DE/
  503. └── ...
  504. ```
  505. With `frameDevice` enabled, framed screenshots are saved to `{outputDirectory}/framed/` (or `framedOutputDirectory` if set).
  506. ### App Info & Categories
  507. ```bash
  508. # View app info, categories, and per-locale metadata
  509. ascelerate apps app-info view <bundle-id>
  510. # List all available category IDs (no bundle ID needed)
  511. ascelerate apps app-info view --list-categories
  512. # Update localization fields for a single locale
  513. ascelerate apps app-info update <bundle-id> --name "My App" --subtitle "Best app ever"
  514. ascelerate apps app-info update <bundle-id> --locale de-DE --name "Meine App"
  515. # Update categories (can combine with localization flags)
  516. ascelerate apps app-info update <bundle-id> --primary-category UTILITIES
  517. ascelerate apps app-info update <bundle-id> --primary-category GAMES_ACTION --secondary-category ENTERTAINMENT
  518. # Export all app info localizations to JSON
  519. ascelerate apps app-info export <bundle-id>
  520. ascelerate apps app-info export <bundle-id> --output app-infos.json
  521. # Bulk update localizations from a JSON file
  522. ascelerate apps app-info import <bundle-id> --file app-infos.json
  523. ```
  524. ### Accessibility Declarations
  525. The App Store's accessibility labels, declared per device family:
  526. ```bash
  527. ascelerate apps accessibility <bundle-id> # view (draft/published per device)
  528. ascelerate apps accessibility set <bundle-id> --device iphone --supports voiceover,larger-text,dark-interface --publish
  529. ascelerate apps accessibility publish <bundle-id> # publish drafts unchanged
  530. ```
  531. `set` declares the full list: features you leave out are declared as not supported.
  532. ### Territory Availability
  533. ```bash
  534. # View which territories the app is available in
  535. ascelerate apps availability <bundle-id>
  536. # Show full country names
  537. ascelerate apps availability <bundle-id> --verbose
  538. # Make territories available or unavailable
  539. ascelerate apps availability <bundle-id> --add CHN,RUS
  540. ascelerate apps availability <bundle-id> --remove CHN
  541. ```
  542. ### App Pricing
  543. ```bash
  544. # Base price, prices set by hand and planned changes (--all: every territory; --json)
  545. ascelerate apps pricing <bundle-id>
  546. ascelerate apps pricing tiers <bundle-id> --territory USA
  547. # Base price, now or from a date (in the base territory's currency; 0 for free)
  548. ascelerate apps pricing set <bundle-id> --price 0.99
  549. ascelerate apps pricing set <bundle-id> --price 1.99 --start-date 2026-12-01
  550. # Prices set by hand: one territory, keep Apple's current prices, or give them back to Apple
  551. ascelerate apps pricing override <bundle-id> --territory FRA --price 0.99
  552. ascelerate apps pricing keep <bundle-id> --territories all
  553. ascelerate apps pricing remove <bundle-id> --territories FRA,DEU
  554. # Temporary price change (a sale), and removing a planned change
  555. ascelerate apps pricing sale <bundle-id> --territories all --price 0.49 --start-date 2026-12-20 --end-date 2026-12-27
  556. ascelerate apps pricing cancel <bundle-id> --territory USA --start-date 2026-12-01
  557. # Copy a schedule to another app (the iap pricing export format)
  558. ascelerate apps pricing export <bundle-id> --output prices.json
  559. ascelerate apps pricing import <other-bundle-id> --file prices.json [--snap]
  560. ```
  561. 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.
  562. ### Encryption Declarations
  563. ```bash
  564. # View existing encryption declarations
  565. ascelerate apps encryption <bundle-id>
  566. # Create a new encryption declaration
  567. ascelerate apps encryption <bundle-id> --create --description "Uses HTTPS for API communication"
  568. ascelerate apps encryption <bundle-id> --create --description "Uses AES encryption" --proprietary-crypto --third-party-crypto
  569. # Attach a compliance document to the newest declaration (or the one --declaration names)
  570. ascelerate apps encryption <bundle-id> --upload-document approval.pdf
  571. ```
  572. 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.
  573. ### App Tags
  574. ```bash
  575. # The tags Apple gives the app on the App Store, and where they're shown
  576. ascelerate apps tags <bundle-id> [--json]
  577. # Hide a tag on the App Store, or show it again
  578. ascelerate apps tags hide <bundle-id> "Photo Editing"
  579. ascelerate apps tags show <bundle-id> "Photo Editing"
  580. ```
  581. Apple chooses an app's tags; you can hide or show each one, by its name or ID.
  582. ### EULA
  583. ```bash
  584. # View the current EULA (or see that the standard Apple EULA applies)
  585. ascelerate apps eula <bundle-id>
  586. # Set a custom EULA from a text file
  587. ascelerate apps eula <bundle-id> --file eula.txt
  588. # Remove the custom EULA (reverts to standard Apple EULA)
  589. ascelerate apps eula <bundle-id> --delete
  590. ```
  591. ### Subscription Grace Period
  592. 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.
  593. ```bash
  594. # View current grace period configuration
  595. ascelerate apps subscription-grace-period <bundle-id>
  596. # Enable for production with a 16-day window, applies to all renewals
  597. ascelerate apps subscription-grace-period <bundle-id> --opt-in true --duration SIXTEEN_DAYS --renewal-type ALL_RENEWALS
  598. # Sandbox testing only (production stays off)
  599. ascelerate apps subscription-grace-period <bundle-id> --sandbox-opt-in true --duration THREE_DAYS --renewal-type ALL_RENEWALS
  600. ```
  601. Valid `--duration` values: `THREE_DAYS`, `SIXTEEN_DAYS`, `TWENTY_EIGHT_DAYS`. Valid `--renewal-type` values: `ALL_RENEWALS`, `PAID_TO_PAID_ONLY`.
  602. 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.
  603. ### Streamlined Purchasing
  604. 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.
  605. ```bash
  606. ascelerate apps streamlined-purchasing <bundle-id> # view
  607. ascelerate apps streamlined-purchasing <bundle-id> --enabled false # turn off
  608. ```
  609. ### Devices
  610. ```bash
  611. # List registered devices
  612. ascelerate devices list
  613. ascelerate devices list --platform IOS --status ENABLED
  614. # Show device details (interactive picker if name/UDID omitted)
  615. ascelerate devices info
  616. ascelerate devices info "My iPhone"
  617. # Register a new device (interactive prompts if options omitted)
  618. ascelerate devices register
  619. ascelerate devices register --name "My iPhone" --udid 00008101-XXXXXXXXXXXX --platform IOS
  620. # Update a device (interactive picker and update prompts if omitted)
  621. ascelerate devices update
  622. ascelerate devices update "My iPhone" --name "Work iPhone"
  623. ascelerate devices update "My iPhone" --status DISABLED
  624. ```
  625. ### Certificates
  626. ```bash
  627. # List signing certificates
  628. ascelerate certs list
  629. ascelerate certs list --type DISTRIBUTION
  630. # Show certificate details (interactive picker if omitted)
  631. ascelerate certs info
  632. ascelerate certs info "Apple Distribution: Example Inc"
  633. # Create a certificate (interactive type picker if --type omitted)
  634. # Auto-generates RSA key pair and CSR, imports into login keychain
  635. ascelerate certs create
  636. ascelerate certs create --type DISTRIBUTION
  637. ascelerate certs create --type DEVELOPMENT --csr my-request.pem
  638. # Revoke a certificate (interactive picker if omitted)
  639. ascelerate certs revoke
  640. ascelerate certs revoke ABC123DEF456
  641. ```
  642. ### Bundle Identifiers
  643. ```bash
  644. # List bundle identifiers
  645. ascelerate bundle-ids list
  646. ascelerate bundle-ids list --platform IOS
  647. # Show details and capabilities (interactive picker if omitted)
  648. ascelerate bundle-ids info
  649. ascelerate bundle-ids info com.example.MyApp
  650. # Register a new bundle ID (interactive prompts if options omitted)
  651. ascelerate bundle-ids register
  652. ascelerate bundle-ids register --name "My App" --identifier com.example.MyApp --platform IOS
  653. # Rename a bundle ID (identifier itself is immutable)
  654. ascelerate bundle-ids update
  655. ascelerate bundle-ids update com.example.MyApp --name "My Renamed App"
  656. # Delete a bundle ID (interactive picker if omitted)
  657. ascelerate bundle-ids delete
  658. ascelerate bundle-ids delete com.example.MyApp
  659. # Enable a capability (interactive pickers if omitted)
  660. # Shows only capabilities not already enabled
  661. ascelerate bundle-ids enable-capability
  662. ascelerate bundle-ids enable-capability com.example.MyApp --type PUSH_NOTIFICATIONS
  663. # Disable a capability (picks from currently enabled capabilities)
  664. ascelerate bundle-ids disable-capability
  665. ascelerate bundle-ids disable-capability com.example.MyApp
  666. ```
  667. 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).
  668. > **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.
  669. ### Provisioning Profiles
  670. ```bash
  671. # List provisioning profiles
  672. ascelerate profiles list
  673. ascelerate profiles list --type IOS_APP_STORE --state ACTIVE
  674. # Show profile details (interactive picker if omitted)
  675. ascelerate profiles info
  676. ascelerate profiles info "My App Store Profile"
  677. # Download a profile (interactive picker if omitted)
  678. ascelerate profiles download
  679. ascelerate profiles download "My App Store Profile" --output ./profiles/
  680. # Create a profile (fully interactive if options omitted)
  681. # Prompts for name, type, bundle ID, certificates, and devices
  682. ascelerate profiles create
  683. ascelerate profiles create --name "My Profile" --type IOS_APP_STORE --bundle-id com.example.MyApp --certificates all
  684. # --certificates all uses all certs of the matching family (distribution, development, or Developer ID)
  685. # You can also specify serial numbers: --certificates ABC123,DEF456
  686. # Delete a profile (interactive picker if omitted)
  687. ascelerate profiles delete
  688. ascelerate profiles delete "My App Store Profile"
  689. # Reissue profiles (delete + recreate with latest certs of matching family)
  690. ascelerate profiles reissue # Interactive: pick from all profiles (shows status)
  691. ascelerate profiles reissue "My Profile" # Reissue a specific profile by name
  692. ascelerate profiles reissue --all-invalid # Reissue all invalid profiles
  693. ascelerate profiles reissue --all # Reissue all profiles regardless of state
  694. ascelerate profiles reissue --all --all-devices # Reissue all, using all enabled devices for dev/adhoc
  695. ascelerate profiles reissue --all --to-certs ABC123,DEF456 # Use specific certificates instead of auto-detect
  696. ```
  697. ### Builds
  698. ```bash
  699. # List all builds (shows app version, platform, and build number)
  700. ascelerate builds list
  701. ascelerate builds list --bundle-id <bundle-id>
  702. ascelerate builds list --bundle-id <bundle-id> --version 2.1.0
  703. ascelerate builds list --bundle-id <bundle-id> --platform macos
  704. # Archive an Xcode project
  705. ascelerate builds archive
  706. ascelerate builds archive --scheme MyApp --output ./archives
  707. ascelerate builds archive --scheme MyApp --json-events # progress as JSON Lines on stdout for other tools
  708. 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)
  709. 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
  710. ascelerate builds archive --scheme MyApp --xcodebuild-output quiet # xcodebuild's warnings and errors only (full: everything)
  711. ascelerate settings --xcodebuild-output quiet # the default for every archive (~/.ascelerate/settings.json; ASCELERATE_XCODEBUILD_OUTPUT for one run)
  712. ascelerate builds archives # Xcode's archives, newest first (--bundle-id, --platform, --json)
  713. # Validate a build before uploading
  714. ascelerate builds validate MyApp.ipa
  715. # Upload a build to App Store Connect
  716. ascelerate builds upload MyApp.ipa
  717. ascelerate builds upload --latest --bundle-id com.example.MyApp --platform macos # the newest archive of an app for one platform
  718. ascelerate builds upload MyApp.ipa --api # upload through the App Store Connect API instead of altool (.ipa or Mac .pkg)
  719. ascelerate builds upload MyApp.xcarchive --api --bundle-id com.example.MyApp # refuse a file holding another app
  720. ascelerate builds upload MyApp.ipa --api --json-events # progress as JSON Lines on stdout for other tools
  721. ascelerate builds uploads <bundle-id> # recent uploads with their state and Apple's errors/warnings
  722. ascelerate builds uploads <bundle-id> --delete-stale # remove upload records that will never complete
  723. # Wait for a build to finish processing
  724. ascelerate builds await-processing <bundle-id>
  725. ascelerate builds await-processing <bundle-id> --build-version 903
  726. ascelerate builds await-processing <bundle-id> --build-version 903 --platform macos
  727. ```
  728. 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.
  729. ### TestFlight
  730. ```bash
  731. # Beta groups
  732. ascelerate testflight groups list <bundle-id>
  733. ascelerate testflight groups info <bundle-id> "External Testers"
  734. ascelerate testflight groups create <bundle-id> --name "Friends" --public-link --public-link-limit 100
  735. ascelerate testflight groups update <bundle-id> "Friends" --public-link false
  736. ascelerate testflight groups update <bundle-id> "Friends" --mac false --vision-pro true # iPhone/iPad builds on Apple silicon Macs, Vision Pro
  737. ascelerate testflight groups delete <bundle-id> "Friends"
  738. # Give a group access to a build (defaults to the latest)
  739. ascelerate testflight groups add-build <bundle-id> "Friends"
  740. ascelerate testflight groups add-build <bundle-id> "Friends" --build 123
  741. ascelerate testflight groups remove-build <bundle-id> "Friends" --build 123
  742. # Public-link recruitment criteria (device/OS filters); Apple no longer adds new ones, set only replaces existing criteria
  743. ascelerate testflight groups criteria view <bundle-id> "Friends" --options
  744. ascelerate testflight groups criteria set <bundle-id> "Friends" --filter IPHONE:18.0 --filter IPAD:17.0:26
  745. ascelerate testflight groups criteria clear <bundle-id> "Friends"
  746. # Testers
  747. ascelerate testflight testers list <bundle-id> --group "Friends"
  748. ascelerate testflight testers add <bundle-id> --email tester@example.com --group "Friends"
  749. ascelerate testflight testers remove <bundle-id> tester@example.com --group "Friends"
  750. ascelerate testflight testers remove <bundle-id> tester@example.com # remove from the whole app
  751. ascelerate testflight testers invite <bundle-id> tester@example.com # re-send the invitation email
  752. ascelerate testflight testers import <bundle-id> --file testers.csv --group "Friends"
  753. # Builds & distribution
  754. ascelerate testflight builds <bundle-id> # TestFlight states per build
  755. ascelerate testflight versions <bundle-id> # pre-release version trains
  756. ascelerate testflight status <bundle-id> --build 123 # processing, testing, and beta review states
  757. ascelerate testflight expire <bundle-id> --build 123
  758. ascelerate testflight notify <bundle-id> # notify testers about the latest build
  759. ascelerate testflight auto-notify <bundle-id> --enabled true
  760. # What to Test (per build, per locale)
  761. ascelerate testflight what-to-test view <bundle-id>
  762. ascelerate testflight what-to-test set <bundle-id> --text "Bug fixes" --locale en-US
  763. ascelerate testflight what-to-test set <bundle-id> --text "Bug fixes" # all existing locales
  764. ascelerate testflight what-to-test copy <bundle-id> --platform ios # newest build gets the newest earlier build's notes
  765. ascelerate testflight what-to-test export <bundle-id> --output notes.json
  766. ascelerate testflight what-to-test import <bundle-id> --file notes.json
  767. # Beta review (required for external testing)
  768. ascelerate testflight submit <bundle-id>
  769. ascelerate testflight app-info view <bundle-id>
  770. ascelerate testflight app-info update <bundle-id> --locale en-US --feedback-email me@example.com
  771. ascelerate testflight review-info <bundle-id> # contact + demo account; pass flags to update
  772. ascelerate testflight eula <bundle-id> --file eula.txt # custom beta license agreement
  773. # Tester feedback
  774. ascelerate testflight feedback crashes list <bundle-id>
  775. ascelerate testflight feedback crashes log <submission-id> --output crash.log
  776. ascelerate testflight feedback screenshots list <bundle-id>
  777. ascelerate testflight feedback screenshots download <bundle-id> # picker; zips screenshots + comment
  778. ```
  779. 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.
  780. ### In-App Purchases
  781. ```bash
  782. # List and inspect
  783. ascelerate iap list <bundle-id>
  784. ascelerate iap list <bundle-id> --type consumable --state approved
  785. ascelerate iap info <bundle-id> <product-id>
  786. # Promoted purchases (shown on the App Store product page)
  787. ascelerate iap promoted list <bundle-id>
  788. ascelerate iap promoted add <bundle-id> <product-id>
  789. ascelerate iap promoted reorder <bundle-id> com.example.a,com.example.b
  790. ascelerate iap promoted toggle <bundle-id> <product-id> --enabled false
  791. ascelerate iap promoted remove <bundle-id> <product-id>
  792. # Create, update, and delete
  793. ascelerate iap create <bundle-id> --name "100 Coins" --product-id <product-id> --type CONSUMABLE
  794. ascelerate iap update <bundle-id> <product-id> --name "100 Gold Coins"
  795. ascelerate iap delete <bundle-id> <product-id>
  796. # Submit for review
  797. ascelerate iap submit <bundle-id> <product-id>
  798. # Manage localizations
  799. ascelerate iap localizations view <bundle-id> <product-id>
  800. ascelerate iap localizations export <bundle-id> <product-id>
  801. ascelerate iap localizations import <bundle-id> <product-id> --file iap-de.json
  802. # Pricing — set the base region price (auto-equalizes to all other territories)
  803. ascelerate iap pricing show <bundle-id> <product-id>
  804. ascelerate iap pricing tiers <bundle-id> <product-id> --territory USA
  805. ascelerate iap pricing set <bundle-id> <product-id> --price 4.99
  806. ascelerate iap pricing set <bundle-id> <product-id> --price 4.99 --base-territory GBR
  807. # Pricing — manage per-territory manual overrides
  808. ascelerate iap pricing override <bundle-id> <product-id> --price 5.99 --territory FRA
  809. ascelerate iap pricing remove <bundle-id> <product-id> --territory FRA
  810. # Pricing — copy the schedule between products (same app or another one)
  811. ascelerate iap pricing export <bundle-id> <product-id> --output prices.json
  812. ascelerate iap pricing import <other-bundle-id> <other-product-id> --file prices.json
  813. # Per-IAP territory availability (independent of the app's territories)
  814. ascelerate iap availability <bundle-id> <product-id>
  815. ascelerate iap availability <bundle-id> <product-id> --add CHN,RUS --remove ITA --available-in-new-territories true
  816. # Offer codes (campaigns + redeem codes)
  817. ascelerate iap offer-code list <bundle-id> <product-id>
  818. 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
  819. ascelerate iap offer-code toggle <bundle-id> <product-id> <offer-code-id> --active true
  820. ascelerate iap offer-code gen-codes <bundle-id> <product-id> <offer-code-id> --count 100 --expires 2026-12-31
  821. ascelerate iap offer-code add-custom-codes <bundle-id> <product-id> <offer-code-id> --code PROMO2026 --count 1000 --expires 2026-12-31
  822. ascelerate iap offer-code view-codes <one-time-use-batch-id> --output codes.txt
  823. # Promotional images + App Review screenshot
  824. ascelerate iap images list <bundle-id> <product-id>
  825. ascelerate iap images upload <bundle-id> <product-id> ./hero.png
  826. ascelerate iap images delete <bundle-id> <product-id> <image-id>
  827. ascelerate iap review-screenshot view <bundle-id> <product-id>
  828. ascelerate iap review-screenshot upload <bundle-id> <product-id> ./review.png
  829. ascelerate iap review-screenshot delete <bundle-id> <product-id>
  830. ```
  831. 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.
  832. `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.
  833. `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.
  834. 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.
  835. 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`.
  836. ### Subscriptions
  837. ```bash
  838. # List and inspect
  839. ascelerate sub groups <bundle-id>
  840. ascelerate sub list <bundle-id>
  841. ascelerate sub info <bundle-id> <product-id>
  842. # Create, update, and delete subscriptions
  843. ascelerate sub create <bundle-id> --name "Monthly" --product-id <product-id> --period ONE_MONTH --group-id <group-id>
  844. ascelerate sub update <bundle-id> <product-id> --name "Monthly Plan"
  845. ascelerate sub delete <bundle-id> <product-id>
  846. # Manage subscription groups
  847. ascelerate sub create-group <bundle-id> --name "Premium"
  848. ascelerate sub update-group <bundle-id> --name "Premium Plus"
  849. ascelerate sub delete-group <bundle-id>
  850. # Submit for review
  851. ascelerate sub submit <bundle-id> <product-id>
  852. # Subscription localizations
  853. ascelerate sub localizations view <bundle-id> <product-id>
  854. ascelerate sub localizations export <bundle-id> <product-id>
  855. ascelerate sub localizations import <bundle-id> <product-id> --file sub-de.json
  856. # Subscription group localizations
  857. ascelerate sub group-localizations view <bundle-id>
  858. ascelerate sub group-localizations export <bundle-id>
  859. ascelerate sub group-localizations import <bundle-id> --file group-de.json
  860. # Pricing — single territory or fan-out across all territories
  861. ascelerate sub pricing show <bundle-id> <product-id>
  862. ascelerate sub pricing tiers <bundle-id> <product-id> --territory USA
  863. ascelerate sub pricing set <bundle-id> <product-id> --price 4.99 --territory USA
  864. ascelerate sub pricing set <bundle-id> <product-id> --price 4.99 --equalize-all-territories
  865. # Standard global price raise: grandfather existing subscribers at the old price
  866. ascelerate sub pricing set <bundle-id> <product-id> --price 9.99 --equalize-all-territories --preserve-current
  867. # Pricing — copy per-territory prices between subscriptions (same app or another one)
  868. ascelerate sub pricing export <bundle-id> <product-id> --output prices.json
  869. ascelerate sub pricing import <other-bundle-id> <other-product-id> --file prices.json --preserve-current
  870. # Per-subscription territory availability (independent of the app's territories)
  871. ascelerate sub availability <bundle-id> <product-id>
  872. ascelerate sub availability <bundle-id> <product-id> --add CHN,RUS --remove ITA --available-in-new-territories true
  873. ascelerate sub availability <bundle-id> <product-id> --plan monthly # the "Monthly with 12-Month Commitment" plan of an annual subscription
  874. # Introductory offers (free trials and intro discounts for new subscribers)
  875. ascelerate sub intro-offer list <bundle-id> <product-id>
  876. ascelerate sub intro-offer create <bundle-id> <product-id> --mode FREE_TRIAL --duration ONE_WEEK --periods 1 --territories all
  877. ascelerate sub intro-offer create <bundle-id> <product-id> --mode PAY_AS_YOU_GO --duration ONE_MONTH --periods 3 --territories USA --price 0.99
  878. ascelerate sub intro-offer update <bundle-id> <product-id> <offer-id> --end-date 2026-12-31
  879. ascelerate sub intro-offer delete <bundle-id> <product-id> <offer-id>
  880. # Promotional offers (server-signed offers for existing subscribers)
  881. ascelerate sub promo-offer list <bundle-id> <product-id>
  882. 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
  883. ascelerate sub promo-offer update <bundle-id> <product-id> <offer-id> --price 5.99 --equalize-all-territories
  884. ascelerate sub promo-offer delete <bundle-id> <product-id> <offer-id>
  885. # Retention messages (shown to subscribers who go to cancel) and retention offers
  886. ascelerate sub retention-message list <bundle-id>
  887. 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."
  888. 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."
  889. ascelerate sub retention-message image upload <bundle-id> "Stay with us" ./retention.png
  890. ascelerate sub retention-message submit <bundle-id> "Stay with us"
  891. 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
  892. ascelerate sub retention-message assign <bundle-id> <product-id> "Stay with us" --offers stay.half
  893. # Win-back offers (for people whose subscription ended; approved subscriptions only)
  894. ascelerate sub win-back-offer list <bundle-id> <product-id>
  895. 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
  896. ascelerate sub win-back-offer update <bundle-id> <product-id> comeback.half --end-date 2027-03-31
  897. ascelerate sub win-back-offer delete <bundle-id> <product-id> comeback.half
  898. # Offer codes (redeemable codes — one-time-use batches and custom codes)
  899. ascelerate sub offer-code list <bundle-id> <product-id>
  900. 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
  901. ascelerate sub offer-code toggle <bundle-id> <product-id> <offer-code-id> --active true
  902. ascelerate sub offer-code gen-codes <bundle-id> <product-id> <offer-code-id> --count 500 --expires 2026-12-31
  903. ascelerate sub offer-code add-custom-codes <bundle-id> <product-id> <offer-code-id> --code SUBPROMO --count 1000 --expires 2026-12-31
  904. ascelerate sub offer-code view-codes <one-time-use-batch-id> --output codes.txt
  905. # Submit a subscription group for review (mirror of `sub submit` but for the whole group)
  906. ascelerate sub submit-group <bundle-id>
  907. # Promotional images + App Review screenshot
  908. ascelerate sub images list <bundle-id> <product-id>
  909. ascelerate sub images upload <bundle-id> <product-id> ./hero.png
  910. ascelerate sub images delete <bundle-id> <product-id> <image-id>
  911. ascelerate sub review-screenshot view <bundle-id> <product-id>
  912. ascelerate sub review-screenshot upload <bundle-id> <product-id> ./review.png
  913. ascelerate sub review-screenshot delete <bundle-id> <product-id>
  914. ```
  915. 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.
  916. The localization import commands create missing locales automatically with confirmation, so you can add new languages without visiting App Store Connect.
  917. `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.
  918. Images and review screenshots use Apple's 3-step upload flow (reserve → PUT chunks → commit with MD5) — `upload` handles all three steps.
  919. **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.
  920. 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.
  921. Apple treats price changes differently for existing subscribers depending on direction — `sub pricing set` enforces this:
  922. - **Decrease**: existing subscribers automatically move to the lower price. Interactive runs prompt; `--yes` mode requires `--confirm-decrease` to acknowledge the revenue impact.
  923. - **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`.
  924. - **New territory** (no existing price): no existing subscribers to consider; flags optional.
  925. - **Unchanged**: skipped silently.
  926. `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.
  927. 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.
  928. ### Sandbox Testers
  929. The Apple Accounts that buy in-app purchases and subscriptions in the sandbox (created in App Store Connect; the API lists and changes them):
  930. ```bash
  931. ascelerate sandbox-testers # list: storefront, renewal rate, interrupted purchases
  932. ascelerate sandbox-testers update tester@example.com --renewal-rate 3m --territory DEU
  933. ascelerate sandbox-testers clear-history tester@example.com # or --all
  934. ```
  935. ### Customer Reviews
  936. ```bash
  937. # List reviews (newest first by default)
  938. ascelerate reviews list <bundle-id>
  939. ascelerate reviews list <bundle-id> --rating 1 --sort critical --unanswered --limit 20
  940. ascelerate reviews list <bundle-id> --territory USA
  941. # Full review text + developer response
  942. ascelerate reviews info <review-id>
  943. # Publish (or replace) a developer response
  944. ascelerate reviews respond <review-id> --body "Thanks for the feedback! ..."
  945. # Delete the developer response
  946. ascelerate reviews delete-response <review-id>
  947. ```
  948. 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.
  949. ### Game Center
  950. Achievements, leaderboards and leaderboard sets, with their languages, images and order:
  951. ```bash
  952. ascelerate game-center <bundle-id> # on or off, counts, default leaderboard
  953. ascelerate game-center enable <bundle-id> # can't be turned off again through the API
  954. ascelerate game-center achievements create <bundle-id> --id first.win --name "First Win" --points 10
  955. ascelerate game-center achievements localizations set <bundle-id> first.win --locale en-US \
  956. --name "First Win" --before-earned "Win a round." --after-earned "You won a round."
  957. ascelerate game-center achievements image upload <bundle-id> first.win --locale en-US icon.png
  958. ascelerate game-center leaderboards create <bundle-id> --id high.score --name "High Score"
  959. ascelerate game-center leaderboards create <bundle-id> --id weekly.time --name "Weekly Time" \
  960. --formatter elapsed-time-second --sort low --recurrence-start 2026-12-07T00:00:00Z \
  961. --recurrence-duration PT168H --recurrence-rule "FREQ=DAILY;INTERVAL=7"
  962. ascelerate game-center sets create <bundle-id> --id all.scores --name "All Scores" --leaderboards high.score,weekly.time
  963. ascelerate game-center activities create <bundle-id> --id duel --name "Duel" --play-style sync --min-players 2 --max-players 2
  964. ascelerate game-center activities link <bundle-id> duel --achievements first.win --leaderboards high.score
  965. ascelerate game-center challenges create <bundle-id> --id beat.score --name "Beat My Score" --leaderboard high.score --repeatable
  966. ascelerate game-center achievements reorder <bundle-id> first.win,high.five
  967. ascelerate game-center achievements submit <bundle-id> first.win # add its new version to the draft submission
  968. ```
  969. 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.
  970. 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`:
  971. ```bash
  972. ascelerate game-center groups # the team's groups with their apps
  973. ascelerate game-center groups create --name "My Games"
  974. ascelerate game-center groups add-app "My Games" <bundle-id> --dry-run
  975. ```
  976. Rule-based matchmaking belongs to the team, so it takes no bundle ID:
  977. ```bash
  978. ascelerate game-center matchmaking rule-sets create --name Ranked --min 2 --max 4
  979. ascelerate game-center matchmaking rules add Ranked --name SameVersion --type compatible \
  980. --expression "requests[0].appVersion == requests[1].appVersion" --description "Same app version"
  981. ascelerate game-center matchmaking teams add Ranked --name Red --min 1 --max 2
  982. ascelerate game-center matchmaking queues create --name RankedQueue --rule-set Ranked
  983. ascelerate game-center matchmaking test Ranked --file requests.json # the matches Apple would make
  984. ```
  985. ### Featuring Nominations
  986. Tell Apple's editorial team about a launch, an update or new content:
  987. ```bash
  988. ascelerate nominations # list (drafts, submitted, archived)
  989. ascelerate nominations create --app <bundle-id> --type enhancements --name "Version 5" \
  990. --description "What's new and why it matters" --publish-start 2026-11-01 --devices iphone,ipad
  991. ascelerate nominations submit <id> # send a draft to Apple
  992. ascelerate nominations update <id> --publish-start 2026-11-08
  993. ascelerate nominations archive <id>
  994. ascelerate nominations delete <id>
  995. ```
  996. `create` saves a draft unless you pass `--submit`. Types: `launch`, `enhancements`, `new-content`.
  997. ### Users
  998. The team's people and invitations: roles, the apps they see, access to Certificates, Identifiers & Profiles:
  999. ```bash
  1000. ascelerate users # everyone, with roles and app access
  1001. ascelerate users info someone@example.com
  1002. ascelerate users update someone@example.com --roles developer,marketing --apps com.example.app
  1003. ascelerate users invite --email new@example.com --first-name Ada --last-name Lovelace --roles developer
  1004. ascelerate users invitations # pending, with expiry; cancel-invitation withdraws one
  1005. ascelerate users remove someone@example.com
  1006. ```
  1007. ### Webhooks
  1008. Have App Store Connect POST an app's events (review state changes, build uploads, TestFlight feedback, …) to your server:
  1009. ```bash
  1010. ascelerate webhooks <bundle-id> # list
  1011. ascelerate webhooks create <bundle-id> --name "Release bot" --url https://example.com/hook \
  1012. --events app-store-version-app-version-state-updated,build-upload-state-updated
  1013. ascelerate webhooks ping <bundle-id> "Release bot" # send a test event
  1014. ascelerate webhooks deliveries <bundle-id> "Release bot" --state failed
  1015. ascelerate webhooks redeliver <delivery-id>
  1016. ascelerate webhooks update <bundle-id> "Release bot" --enabled false
  1017. ascelerate webhooks delete <bundle-id> "Release bot"
  1018. ```
  1019. Without `--secret`, `create` generates a signing secret and prints it once. `--events all` subscribes to every event type.
  1020. ### Xcode Cloud
  1021. Follow and start Xcode Cloud builds. A product is set up once in Xcode (Integrate > Create Workflow); after that:
  1022. ```bash
  1023. ascelerate xcode-cloud products # apps and frameworks
  1024. ascelerate xcode-cloud workflows <bundle-id> # list; also info, enable, disable, delete
  1025. ascelerate xcode-cloud workflows update <bundle-id> "Default" --manual-only # stop automatic builds
  1026. ascelerate xcode-cloud workflows update <bundle-id> "Release" --branch-changes "main,release/*" --xcode "Xcode 27.2"
  1027. ascelerate xcode-cloud workflows create <bundle-id> --like "Default" --name "TestFlight" --action archive:MyApp:ios
  1028. ascelerate xcode-cloud runs <bundle-id> [--workflow "Release"] # build runs, newest first
  1029. ascelerate xcode-cloud runs info <bundle-id> 42 # details, actions, the build it uploaded
  1030. ascelerate xcode-cloud runs issues <bundle-id> 42 # errors and warnings
  1031. ascelerate xcode-cloud runs tests <bundle-id> 42 --failed
  1032. ascelerate xcode-cloud runs logs <bundle-id> 42 --show ci_post_clone.log # log bundle: post-clone, packages, xcodebuild
  1033. ascelerate xcode-cloud runs artifacts <bundle-id> 42 --download ./artifacts
  1034. ascelerate xcode-cloud start <bundle-id> "Release" --branch main # or --tag, --pull-request
  1035. ascelerate xcode-cloud rerun <bundle-id> 42
  1036. ascelerate xcode-cloud xcode-versions # Xcode and macOS versions offered
  1037. ```
  1038. ### In-App Events
  1039. ```bash
  1040. # List and inspect
  1041. ascelerate events list <bundle-id>
  1042. ascelerate events list <bundle-id> --state PUBLISHED
  1043. ascelerate events info <bundle-id> <reference-name-or-id>
  1044. # Create, update, delete (events are referenced by name or ID)
  1045. ascelerate events create <bundle-id> --reference-name "summer-sale" --badge SPECIAL_EVENT --purpose ATTRACT_NEW_USERS --priority HIGH
  1046. 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
  1047. ascelerate events update <bundle-id> summer-sale --priority NORMAL --badge NONE
  1048. ascelerate events delete <bundle-id> summer-sale
  1049. # Localizations (name, short description, long description per locale)
  1050. ascelerate events localizations view <bundle-id> summer-sale
  1051. ascelerate events localizations export <bundle-id> summer-sale
  1052. ascelerate events localizations import <bundle-id> summer-sale --file event-locales.json
  1053. # Media — event card / details page screenshots and video clips
  1054. ascelerate events media list <bundle-id> summer-sale
  1055. ascelerate events media upload <bundle-id> summer-sale --locale en-US --asset-type EVENT_CARD card.png
  1056. ascelerate events media upload <bundle-id> summer-sale --locale en-US --asset-type EVENT_DETAILS_PAGE clip.mp4 --preview-frame 00:00:03:00
  1057. ascelerate events media delete <bundle-id> summer-sale <media-id>
  1058. ```
  1059. 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`).
  1060. ### Custom Product Pages
  1061. ```bash
  1062. # List and inspect
  1063. ascelerate product-pages list <bundle-id>
  1064. ascelerate product-pages info <bundle-id> <name-or-id>
  1065. # Create — the API requires a first version + localization, so --locale is required
  1066. ascelerate product-pages create <bundle-id> --name "Summer Campaign" --locale en-US --promotional-text "Limited-time offer"
  1067. # Rename or toggle App Store visibility
  1068. ascelerate product-pages update <bundle-id> "Summer Campaign" --name "Summer 2026" --visible false
  1069. ascelerate product-pages delete <bundle-id> "Summer Campaign"
  1070. # Localizations (promotional text per locale)
  1071. ascelerate product-pages localizations view <bundle-id> "Summer 2026"
  1072. ascelerate product-pages localizations export <bundle-id> "Summer 2026"
  1073. ascelerate product-pages localizations import <bundle-id> "Summer 2026" --file page-locales.json
  1074. # Screenshots & app previews (sets created on first upload)
  1075. ascelerate product-pages media list <bundle-id> "Summer 2026"
  1076. ascelerate product-pages media upload <bundle-id> "Summer 2026" --locale en-US --display-type APP_IPHONE_67 screenshot.png
  1077. 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
  1078. ascelerate product-pages media delete <bundle-id> "Summer 2026" <media-id>
  1079. ```
  1080. Pages are referenced by name or ID. Each page's shareable App Store URL (with its `ppid`) appears in `list` and `info`.
  1081. ### Product Page Optimization
  1082. A/B test screenshots, previews and app icons against the original product page:
  1083. ```bash
  1084. ascelerate experiments <bundle-id> # list tests
  1085. ascelerate experiments create <bundle-id> --name "Screenshot order" --traffic 50 --treatment "Map first"
  1086. ascelerate experiments media upload <bundle-id> "Screenshot order" "Map first" --locale en-US --display-type APP_IPHONE_67 01.png
  1087. ascelerate experiments info <bundle-id> "Screenshot order" # treatments, locales and media
  1088. ascelerate experiments submit <bundle-id> "Screenshot order" # App Review
  1089. ascelerate experiments start <bundle-id> "Screenshot order" # once approved
  1090. ascelerate experiments stop <bundle-id> "Screenshot order"
  1091. ```
  1092. `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.
  1093. ### Reports
  1094. 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`).
  1095. ```bash
  1096. # Sales & Trends — units/downloads, proceeds, IAP/subscription activity
  1097. ascelerate reports sales # most recent day, all apps
  1098. ascelerate reports sales --frequency WEEKLY
  1099. ascelerate reports sales --frequency MONTHLY --date 2026-05
  1100. ascelerate reports sales --frequency YEARLY --date 2025 --bundle-id com.example.App
  1101. ascelerate reports sales --frequency DAILY --date 2026-06-20 --output sales.tsv
  1102. # Financial report — units + partner proceeds for a fiscal period, by region
  1103. ascelerate reports finance --date 2026-05 --region US
  1104. ascelerate reports finance --date 2026-05 --region US --type FINANCE_DETAIL --output finance.tsv
  1105. # App Analytics — downloads, impressions, sessions (async: creates/reuses a report request)
  1106. ascelerate reports analytics <bundle-id>
  1107. ascelerate reports analytics <bundle-id> --category APP_USAGE --granularity WEEKLY
  1108. ```
  1109. - `reports sales` / `reports finance` need a **vendor number** (App Store Connect → Payments and Financial Reports). Save it with `configure` or pass `--vendor-number`.
  1110. - 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.
  1111. - 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.
  1112. - The API does not expose aggregate rating counts or the star-rating average — only individual reviews (see Customer Reviews).
  1113. ### Diagnostics
  1114. 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`):
  1115. ```bash
  1116. ascelerate diagnostics <bundle-id> # signatures by type, heaviest first
  1117. ascelerate diagnostics logs <signature-id> # sampled events with call stacks (▶ blamed frame)
  1118. ascelerate diagnostics metrics <bundle-id> [--type launch,hang] [--all] # per version, 50th/90th percentile; regressions first
  1119. ```
  1120. ### Apple Ads
  1121. 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.
  1122. ```bash
  1123. # One-time setup: creates the key pair, prints the public key to paste into
  1124. # Apple Ads → Account Settings → API, then asks for clientId/teamId/keyId
  1125. ascelerate ads configure
  1126. # Performance (--days N or --from/--to; --app, --campaign; --json)
  1127. ascelerate ads reports campaigns --days 30
  1128. ascelerate ads reports campaigns --campaign "MyApp US" --by device # also age, gender, country, region, city
  1129. ascelerate ads reports keywords --campaign "MyApp US" # with Apple's suggested bid
  1130. ascelerate ads reports search-terms --app myapp # what people searched, which keyword matched
  1131. # Campaigns, keywords, negatives (writes confirm first; --dry-run shows the requests)
  1132. ascelerate ads campaigns list
  1133. ascelerate ads campaigns pause "MyApp US"
  1134. ascelerate ads campaigns budget "MyApp US" --daily 120
  1135. 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
  1136. ascelerate ads keywords add --campaign "MyApp US" --match exact --bid 1.50 "qr scanner" "barcode reader"
  1137. ascelerate ads keywords bid --campaign "MyApp US" --bid 1.25 "qr scanner"
  1138. ascelerate ads negatives add --campaign "MyApp US" "free wifi"
  1139. ascelerate ads adgroups create --campaign "MyApp US" --name "Exact" --search-match off # copy of the existing group, paused
  1140. ascelerate ads keywords copy --campaign "MyApp US" --from "US Ad Group" --to "Exact"
  1141. ascelerate ads reports adgroups --campaign "MyApp US"
  1142. # What to change: search terms to add as keywords, give their own bid, or exclude
  1143. ascelerate ads opportunities --app myapp
  1144. ascelerate ads recommendations apply <id>
  1145. ascelerate ads campaigns target-cpa --app myapp --country US # Apple's suggested Max Conversions target
  1146. ascelerate ads history --app myapp --days 7 # who changed what, old → new
  1147. # Ad variations: send an ad group's taps to a custom product page (made in App Store Connect)
  1148. ascelerate ads product-pages --app myapp
  1149. ascelerate ads ads create --campaign "MyApp US" --ad-group "Scanner" --product-page "Scanner Page" --enabled
  1150. ascelerate ads reports ads --campaign "MyApp US"
  1151. # Keyword research and market insights
  1152. ascelerate ads keywords suggest --app myapp --seed "qr code" --country US
  1153. ascelerate ads keywords popularity --app myapp --country US --term "qr code" "qr scanner"
  1154. ascelerate ads insights impression-share --app myapp --country US
  1155. ascelerate ads recommendations
  1156. ```
  1157. - 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`.
  1158. - 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%.
  1159. - Search terms Apple withholds for privacy show as "(low volume)"; keyword suggestions are only relevant with `--seed`.
  1160. - 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.
  1161. ### Rate Limit
  1162. Check your current API usage against the rolling hourly quota:
  1163. ```bash
  1164. ascelerate rate-limit
  1165. ```
  1166. ```
  1167. Hourly limit: 3600 requests (rolling window)
  1168. Used: 57
  1169. Remaining: 3543 (98%)
  1170. ```
  1171. ### Workflows
  1172. Chain multiple commands into a single automated run with a workflow file:
  1173. ```bash
  1174. ascelerate run-workflow release.txt
  1175. ascelerate run-workflow release.txt --yes # skip all prompts (CI/CD)
  1176. ascelerate run-workflow # interactively select from .workflow/.txt files
  1177. ascelerate run-workflow release.txt --check # every step parses (--json: each step's line and error); nothing runs
  1178. ascelerate run-workflow release.txt --json-events # JSON events on stdout (steps, outcomes, prompts answered on stdin); output on stderr
  1179. ```
  1180. 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.
  1181. **Example** -- `release.txt` for submitting version 2.1.0 of a sample app:
  1182. ```
  1183. # Release workflow for MyApp v2.1.0
  1184. # Create the new version on App Store Connect
  1185. apps create-version com.example.MyApp 2.1.0
  1186. # Build, validate, and upload
  1187. builds archive --scheme MyApp
  1188. builds validate --latest --bundle-id com.example.MyApp
  1189. builds upload --latest --bundle-id com.example.MyApp
  1190. # Wait for the build to finish processing
  1191. builds await-processing com.example.MyApp
  1192. # Update localizations and attach the build
  1193. apps localizations import com.example.MyApp --file localizations.json
  1194. apps build attach-latest com.example.MyApp
  1195. # Submit for review
  1196. apps review submit com.example.MyApp
  1197. ```
  1198. 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.
  1199. ### Automation
  1200. 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):
  1201. ```bash
  1202. ascelerate apps build attach-latest <bundle-id> --yes
  1203. ascelerate apps review submit <bundle-id> --yes
  1204. ```
  1205. On universal-purchase apps, also pass `--platform` so unattended runs never hit the interactive platform-disambiguation prompt.
  1206. ### Dry run
  1207. 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.
  1208. ```bash
  1209. ascelerate apps localizations import <bundle-id> --file localizations.json --yes --dry-run
  1210. ascelerate run-workflow release.txt --yes --dry-run
  1211. ASCELERATE_DRY_RUN=1 ascelerate run-workflow release.txt --yes # same, e.g. for a whole CI job
  1212. ```
  1213. 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.
  1214. ### API rate limit
  1215. 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.
  1216. ### Upload chunks
  1217. 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.
  1218. ```bash
  1219. ASCELERATE_PARALLEL_CHUNKS=4 ascelerate apps media upload <bundle-id> media/
  1220. ```
  1221. ### Version
  1222. ```bash
  1223. ascelerate version # Prints version number
  1224. ascelerate --version # Same as above
  1225. ascelerate -v # Same as above
  1226. ```
  1227. ## Acknowledgments
  1228. Versions up to 0.21 were built on top of [asc-swift](https://github.com/aaronsky/asc-swift) by Aaron Sky. Thank you!
  1229. *"A Swift Client, App Store Connect"* — [@validatedev](https://x.com/validatedev/status/2026613415012118674)
  1230. 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.
  1231. Developed with [Claude Code](https://claude.ai/code).
  1232. ## License
  1233. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.