appuploader cli

Summary

appuploader-cli is the command-line tool of App Uploader. On Windows, Linux and macOS it handles every step of an iOS release with commands: signing in, registering Bundle IDs, issuing certificates, creating provisioning profiles, creating the app in App Store Connect, uploading the IPA, importing metadata and screenshots, submitting for App Review and distributing on TestFlight. This guide covers where to find it, how to sign in, the common commands, the one-command release pipeline, and how to use it in CI and with AI agents. Every command is documented in full in the appuploader-cli command manual.

---

1. Where to find appuploader-cli

appuploader-cli ships with the App Uploader app, so there is nothing extra to download. After installing the app, it is in the install folder:

System	Path
macOS	AppUploader.app/Contents/Resources/appuploader-cli
Windows	appuploader-cli.exe next to AppUploader.exe
Linux	appuploader-cli next to AppUploader

Add that folder to your PATH so you can run appuploader-cli from any directory.

appuploader-cli shares the data folder ~/appuploader-data-v6/ with the App Uploader app. An account you signed in there works on the command line, and the other way round.

appuploader-cli uses your App Uploader license. No separate license is needed.

---

2. Up and running in five minutes

 1# 1. Sign in with your Apple ID and an app-specific password (recommended, no two-factor prompt)
 2APPLE_PW='xxxx-xxxx-xxxx-xxxx' appuploader-cli login --apple-id dev@example.com --password-env APPLE_PW --alias dev
 3
 4# 2. Generate the project config in your app folder and edit it
 5appuploader-cli init --bundle-id com.example.app --name "My App"
 6
 7# 3. Check, dry-run, release
 8appuploader-cli doctor --for-release
 9appuploader-cli release --dry-run
10appuploader-cli release

Every command has a description and examples. Run appuploader-cli <command> --help to see them.

---

3. Signing in

The session is saved in the data folder and reused by later commands.

Recommended: Apple ID + app-specific password

We recommend it for three reasons:

• No two-factor authentication, so scripts, CI and AI agents can sign in unattended.
• The full feature set, including creating apps, accepting agreements, pricing and privacy labels.
• Revocable on its own at any time, so a leaked password does not affect your Apple ID.

How to generate one:

1. Sign in to account.apple.com with your Apple ID.
2. Under “Sign-In and Security”, open “App-Specific Passwords” and generate one with any label.
3. Copy the password. It is shown only once, so save it right away. Two-factor authentication must be enabled on the account to generate one.

For step-by-step screenshots, see Generate App-Specific Password.

Put the password in an environment variable and pass its name with --password-env. The tool recognizes an app-specific password by its format:

1APPLE_PW='xxxx-xxxx-xxxx-xxxx' appuploader-cli login --apple-id dev@example.com --password-env APPLE_PW --alias dev

Other ways to sign in

Account	How to sign in	Notes
Apple ID + regular password	Same as above, with your Apple ID password	May trigger two-factor authentication
App Store Connect API Key	--api-key-file AuthKey_X.json, or --api-key-id + --api-issuer-id + --api-key-path AuthKey_X.p8	No two-factor authentication, but Apple’s official API cannot create apps, accept agreements or set privacy labels
Free Apple ID	Add --free	For accounts without a paid developer membership; manages certificates, Bundle IDs, profiles and devices

Two-factor authentication: with a regular password, a terminal prompts for the code. In scripts, pass --2fa-code 123456, or use --2fa-from-file /tmp/code.txt so the login process waits for another process to write the code into that file. An app-specific password avoids this entirely.

Common account commands:

1appuploader-cli account list        # signed-in accounts and whether sessions are valid
2appuploader-cli whoami              # which account and team commands will use
3appuploader-cli team list           # list teams
4appuploader-cli team use <team-id>  # set the default team
5appuploader-cli logout              # clear the session

---

4. Uploading an IPA

If you only need to upload an IPA, one command does it after signing in:

1appuploader-cli build upload ./build/MyApp.ipa
2appuploader-cli build wait <build-number> --timeout 45m   # wait for Apple to finish processing

The old form appuploader-cli upload -f x.ipa -u … -p … still works. We recommend running login first and then build upload.

---

5. Certificates, profiles and devices

1appuploader-cli bundle create com.example.app --name "My App" --cap PUSH_NOTIFICATIONS   # register the Bundle ID and add capabilities
2P12_PW=… appuploader-cli cert create --type IOS_DISTRIBUTION --out ./signing --p12-password-env P12_PW   # issue a distribution certificate as .p12
3appuploader-cli device import devices.txt                                  # import test devices in bulk
4appuploader-cli profile create "MyApp AppStore" --type IOS_APP_STORE --out ./signing   # create a provisioning profile
5appuploader-cli signing                                                    # prepare every signing asset from the project config

• cert create reuses a valid certificate first and only issues a new one when needed. The private key is generated locally and the .p12 is protected with the password from the environment variable.
• profile create picks the certificate and devices automatically, reuses a matching profile and rebuilds an expired one.

---

6. One-command release

release runs the whole submission from the project config appuploader.yaml:

preflight → bundle → certs → profiles → app → version → upload → metadata → screenshots → custom-pages
→ build-wait → compliance → review-info → gamecenter → iap → pricing → privacy → submit → testflight

• Every step is repeatable: existing records are skipped, valid certificates are reused and uploaded builds are not uploaded again.
• If a run fails, run the same command again and it continues from the failed step. --restart starts over and --from <step> picks the starting step.
• --dry-run is read-only and reports what each step would do.
• --skip, --only, --from and --to trim the steps to run.
• Optional steps such as in-app purchases, pricing, privacy labels and TestFlight run only when the project config includes them.
• Publishing is not part of the pipeline. With a manual release type, once App Review approves the version you publish it yourself with appuploader-cli version publish <version>.

---

7. Metadata, screenshots and the asset library

1appuploader-cli init --from-app                      # export live metadata so you can keep it in git
2appuploader-cli metadata import                      # import metadata; only fields present and non-empty are written
3appuploader-cli screenshot upload ./screenshots/     # screenshots are sorted into device slots by pixel size
4appuploader-cli asset place --locale en-US ./duo/    # asset library: replace the iPhone Duo screenshots for a language
5appuploader-cli custom-page create "Spring" --from-version   # new custom product page from the current version

From April 2027, Apple requires iPhone Duo screenshots for every submission. App Uploader already supports them.

---

8. Using it in CI

In CI, we recommend an Apple ID with an app-specific password, which never hits two-factor authentication. With the environment variables below set, there is no need to run login first; commands sign in when needed:

• APPUPLOADER_APPLE_ID: the Apple ID
• APPUPLOADER_PASSWORD: the app-specific password

You can use an API Key instead, with APPUPLOADER_API_KEY_ID, APPUPLOADER_API_ISSUER_ID, and either APPUPLOADER_API_KEY_P8 (the contents of the .p8) or APPUPLOADER_API_KEY_PATH (the path to the .p8).

1appuploader-cli release --json --yes

In --json mode every step prints one JSON line. A failure says whether it can be retried and which command to run next, so your pipeline can parse it.

---

9. Handing it to an AI agent

appuploader-cli can generate a skill file for Claude Code, Codex and other AI agents:

1appuploader-cli skill --install user                  # install for Claude Code in every project
2appuploader-cli skill --install project               # install for the current project only
3appuploader-cli skill --format agents >> AGENTS.md    # instructions for other agents

The skill file covers the usage rules, exit codes and retry policy, common workflows and the full command index. Once it is installed, tell the agent in plain language which version to release. Regenerate it after upgrading the tool.

---

10. Full command manual

This guide covers the most common commands. For every appuploader-cli command, with every flag and examples, see the appuploader-cli command manual.