altool(1) General Commands Manual altool(1)

xcrun altool -- Validate and Upload apps for the App Store, or Notarize apps for distribution outside of the Mac App Store.

xcrun altool --upload-package file_path --type {macos | ios | appletvos} --asc-public-id id --apple-id id --bundle-version version --bundle-short-version-string string --bundle-id id {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id}

xcrun altool --validate-app -f file_path --type "{macos | ios | appletvos}" {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id}

xcrun altool --upload-app -f file_path --type "{macos | ios | appletvos}" {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id} [DEPRECATED use --upload-package]

xcrun altool --upload-hosted-content file_path --sku sku --type "{macos | ios | appletvos}" --product-id id --asc-provider id

xcrun altool --notarize-app -f file_path --primary-bundle-id bundle_id {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id} [--asc-provider name | --team-id id | --asc-public-id id]

xcrun altool --notarization-info uuid {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id}

xcrun altool --notarization-history page {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id} [--asc-provider name | --team-id id | --asc-public-id id]

xcrun altool --list-apps {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id}

xcrun altool --list-providers {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id}

xcrun altool --store-password-in-keychain-item name_for_keychain_item -u username -p password [--keychain keychain_filename | --sync]

To upload or notarize your app binary files, you can use the xcrun altool command-line tool in Xcode 10.0 or later.

To run altool from Xcode to upload or notarize your app, specify the following at the command-line:

xcrun altool command [...]

Note: Most functions require authentication, but you can pass in your credentials via Environment Variables or the keychain. See the -p parameter below.

Usage

altool supports various usages depending on if you need to deliver an app for distribution via the App Store or to notarize a macOS app for distribution outside of the Mac App Store.

The --validate-app and --upload-package commands are used for App Store distribution.

The --notarize-app, --notarization-info and --notarization-history commands are used when notarizing macOS apps and retrieving information about apps previously notarized.

Authentication

Most commands require authorization, but you can pass in your credentials via Environment Variables or the keychain. See the -p parameter below.

Two methods of authentication are available: username with password, and apiKey with apiIssuer.

Username. Required to connect for most commands. You must also specify --password.

Password. Required if --username is specified. If this argument is not supplied on the command line, it will be read from stdin. Alternatively to entering password in plaintext, the password may also be specified using a '@keychain:' or '@env:' prefix followed by a keychain password item name or environment variable name.

Example:
'-p @keychain:MY_PASS' uses the password stored in the keychain password item named MY_PASS.

You can create and update keychain items with the --store-password-in-keychain-item command. Note also that the --username can be inferred from the keychain item so --username can be omitted when using a '-p @keychain:' option. Optionally, you can specify a custom keychain file that contains the password with the --keychain option.

Example: '-p @env:MY_PASS' uses the value in the environment variable named MY_PASS.

apiKey. Required for JWT authentication (in lieu of username/password). This option will search the following directories in sequence for a private key file with the name of 'AuthKey_<api_key>.p8': './private_keys', '~/private_keys', '~/.private_keys', and '~/.appstoreconnect/private_keys'. Additionally, you can set the environment variable $API_PRIVATE_KEYS_DIR or a user default API_PRIVATE_KEYS_DIR to specify the directory where your AuthKey file is located.

Issuer ID. Required if --apiKey is specified.

Keychain Usage

Stores the password password in the keychain item named name_for_keychain_item associated with the account username. If an item with that name and account already exists in the keychain, its password will be updated. Otherwise a new item is created with that name. You can use this keychain item with the -p option to mask your password with other commands. Optionally, you can specify a custom keychain file in which to store the password with the --keychain option. You can also use --sync to create a password that will sync with your iCloud account.

Example:
xcrun altool --store-password-in-keychain-item "MY_SECRET" -u jappleseed@apple.com -p "MyP@ssw0rd!@78"

xcrun altool --notarize-app -u jappleseed@apple.com -p @keychain:MY_SECRET [...]

Used with --store-password-in-keychain and the @keychain: option for -p lets you specify the path to a keychain file in which to store or from which to read the password. Cannot be used with the --sync option.

Used with --store-password-in-keychain to allow the keychain item to sync with your iCloud account and other devices associated with the account. Cannot by used with the --keychain option.

General

file specifies the path to the file to process.
Specify the platform of the file.
Allows you to specify the protocol used when using --upload-package, --upload-app, or --notarize-app. You should only use this option when instructed by Apple.
Allows you to limit the upload speed to Kbps kilobits per second. If not specified, then the default limit is used.
Specify the Apple ID of the app to be uploaded with --upload-package.
Specify the CFBundleIdentifier of the app to be uploaded with --upload-package.
Specify the CFBundleShortVersionString of the app to be uploaded with --upload-package.
Specify the CFBundleVersion of the app to be uploaded with --upload-package.
Specify the product ID of the hosted content package to be uploaded with --upload-hosted-content.
Specify the SKU of the hosting app associated with the hosted content to be uploaded with --upload-hosted-content.
Required with --notarize-app and --notarization-history when a user account is associated with multiple providers and using username/password authentication. You can use the --list-providers command to retrieve the providers associated with your accounts. You may instead use --asc-public-id or --team-id.
Required with --upload-package, --notarize-app, and --notarization-history when a user account is associated with multiple providers and using username/password authentication. You can use the --list-providers command to retrieve the providers associated with your account. You may instead use --asc-provider or --team-id.
Required with --notarize-app and --notarization-history when a user account is associated with multiple providers and using username/password authentication. You can use the --list-providers command to retrieve the providers associated with your accounts. You may instead use --asc-provider or --asc-public-id.
Displays a list of the providers associated with your account along with short name, team id, and public id. This command is useful to determine what to use with the --asc-provider, --team-id, and --asc-public-id options. Authentication is required.
Specifies how the output is formatted. 'xml' and 'json' display the output in a structured format; 'normal' displays in an unstructured format (default).
Show progress during operation.
Enable logging output. Show detailed information during operation.
Display the help page.

App Store Apps

Uploads the app archive for App Store submission. file_path, --type, --asc-public-id, --apple-id, --bundle-version, --bundle-short-version-string, --bundle-id, and Authentication are required.

Preflights an app archive for App Store submission. Authentication and -f are required. Information about the archive is sent to the App Store for evaluation. This mode is useful for identifying issues which need to be corrected prior to uploading the entire archive. If successful, the app can be submitted with --upload-app. If the archive fails validation, a list of errors is returned which can be addressed prior to upload. Validation is not required prior to uploading.

Uploads the given app archive for App Store submission. Authentication and -f are required. The app archive is submitted to the App Store. If successful, the app begins the process for being accepted into the App Store. If the upload is rejected, a list of errors is returned that need to be addressed before uploading again. It may be useful to use --validate-app first to catch common problems without uploading the entire package.

Uploads the specified hosted content in-app purchase archive to the App Store. --sku, --type, --product-id, --asc-provider, and Authentication are required.

Returns a list of all app records associated with your account(s). Authentication is required.

Notarizing Apps

Uploads the given app package, dmg or zip file for notarization. Authentication, -f, and --primary-bundle-id are required. --asc-provider, --asc-public-id, or --team-id is required for an account associated with multiple providers. If successful, the UUID associated with the upload is returned. You can query the status of the upload with the --notarization-info command and specifying the UUID.

Returns the status and log file URL of a package previously uploaded for notarization with the specified uuid. Authentication is required. The log file can be retrieved with 'curl log_file_url'.

Returns a list of all uploads submitted for notarization. page specifies a range of entries where 0 returns the most recent number of entries. A new page value will be returned which can be used as the page value to the next use of --notarization-history and so forth until no more items are returned. Authentication is required. --asc-provider, --asc-public-id, or --team-id is required for an account associated with multiple providers.

Used with --notarize-app to uniquely identify a package.

0 success, 1 failure. (Upon failure, an error code and message are generally also displayed.)

xcrun altool --upload-package MyApp.ipa --type ios --asc-public-id 69a6de71-xxxx-xxxx-xxxx-xxxxxxxxxxxx --apple-id 42xxxx --bundle-version '5' --bundle-short-version-string '1.0' --bundle-id 'com.mycompany.myapp' -u user@mycompany.com -p **********

Uploads the package for App Store submission. The result is either success or a list of errors that need to be addressed before the upload is accepted.

xcrun altool --validate-app -f file -t platform {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id}

Preflights the app for App Store submission. The result is either success or a list of errors that need to be addressed prior to upload.

xcrun altool --upload-app -f file -t platform {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id}

Uploads the app for App Store submission. The result is either success or a list of errors that need to be addressed before the upload is accepted.

xcrun altool --list-apps {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id}

Returns a list of all app records associated with your account.

xcrun altool --notarize-app -f file --primary-bundle-id bundle_id {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id} [--asc-provider provider_shortname | --team-id wwdr_team_id]

Uploads the macOS package to be notarized and identified with bundle_id. A successful upload returns a uuid assigned to that upload.

xcrun altool --notarization-info uuid {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id}

Returns the status of a package that was previously submitted with --notarize-app which returned uuid.

xcrun altool --notarization-history page {-u username [-p password] | --apiKey api_key --apiIssuer issuer_id} [--asc-provider provider_shortname | --team-id wwdr_team_id]

Returns a list of packages that were previously submitted with --notarize-app along with a new page value that can be used in a subsequent call to --notarization-history to list additional items.

xcrun(1)

19 MAR 2021