Get started

altool overview

This guide describes altool, a command-line tool that ships with Xcode used for validating and uploading your app binary files to the App Store.

Requirements

To run altool, you must have a Mac running macOS 10.11 or later with at least 512 MB RAM. Apple recommends a broadband internet connection with an upload rate of 1MB/sec or faster.

Notarization requires Xcode 10 or later. Building a new app for notarization requires macOS 10.13.6 or later. Stapling an app requires macOS 10.12 or later.

The command line tool, (called altool), works within the Xcode development environment to deliver binary files directly from Xcode. For more information on this delivery mechanism, see Upload an app to App Store Connect in the Xcode help.

To view details about the servers used to deliver files, check the listing of network servers in the Transporter User Guide. For the best upload experience, verify that all of the ports and IP addresses are accessible.

Supported formats

altool supports the following file formats:

  • IPA files (.ipa) for delivering your iOS and tvOS apps.

  • PKG package files (.pkg) for delivering your OS X and macOS apps. For information about how to use productbuild to create a package file, see the productbuild manual page at x-man-page://1/productbuild.

Access altool

You access altool (a command line utility from the Xcode toolchain) using Terminal.

Xcode is Apple’s integrated development environment (IDE). Xcode provides tools to manage your entire development workflow—from creating your app to testing, optimizing, and submitting it to the App Store. See Xcode Help for more information.

Access altool

  1. Make sure you have Xcode (Xcode.app) installed on your computer.

    By default, the installation package installs Xcode in your Applications folder.

  2. In Terminal, use xcrun to invoke altool.

You are now ready to begin using altool. For more information, see About delivering your app binary.

Xcode includes the platform Software Development Kit (SDK) for iOS, tvOS, macOS, and watchOS (located in the Platforms folder of the Xcode bundle). Use the App Store to download the current versions of Xcode and the SDKs.

Deliver your app

About delivering your app binary

After you add an app to your account on App Store Connect, you can deliver your app binary files to the App Store.

This section describes altool, a command-line tool for validating and uploading your app binary files to the App Store (see Validate and upload your app binary files with altool). You can also notarize your app using altool (see Upload and notarize your app binary files with altool).

Before uploading your app, validate the archive to determine whether it meets minimum App Store requirements and ensure that it passes standard App Store Connect checks.

Note: Validation is different from notarization. With validation, the App Store checks your app to make sure it meets app requirements and standards. With notarization, Apple checks your app prior to distribution to ensure it does not include malicious software.

Two-factor authentication

If you have enabled two-factor authentication on your account, you must create an app-specific password, as described in Using app-specific passwords. Using an app-specific password increases the level of security and ensures your Apple ID password won’t be collected or stored by third-party apps.

Validate and upload your app binary files with altool

You can use xcrun (included with Xcode) to invoke altool, a command-line tool that lets you notarize apps for independent distribution, and validate and upload your app binary files for distribution via the App Store. Specify one of the following in Terminal at the command-line:

$ xcrun altool --validate-app -f file -t platform -u username [-p password] [--output-format xml]$ xcrun altool --upload-package package -t platform --asc-public-id public_id --apple-id apple_id --bundle-id bundle_id --bundle-short-version-string version_string --bundle-version bundle_version -u username [-p password] [--output-format xml]$ xcrun altool --upload-app -f file -t platform -u username [-p password] [--output-format xml]

Note: The --upload-app command is deprecated. Use the --upload-package command instead.

Parameters

Description

--validate-app

You want to validate the specified app. Validation determines whether the app meets minimum App Store requirements and ensures that it passes standard App Store Connect checks.

--upload-package package

You want to upload the specified package to the App Store.

package is the path and filename for the app archive package that you are uploading.

Note: For the --upload-package command, you specify the path and filename for the package you are uploading without the -f flag.

--upload-app

You want to upload the specified app to the App Store.

Note: The --upload-app command is deprecated. Use the --upload-package command instead.

-f file

The path and filename for the app you are validating with the --validate-app command or uploading with the --upload-app command.

-t platform

Optional. The platform of the file. Options can be: osx, ios, or appletvos.

-u username

Your user name. Note that the username you specify is your App Store Connect user name.

Note: If you use the username option, you must specify the password or use apiKey / apiIssuer authentication.

-p password

Your user password. The password is required if you specify username and you do not specify apiKey / apiIssuer. If you do not specify password on the command line, it will be read from stdin.

As an alternative to entering password in plain text, you can instead specify it using a @keychain: or @env: prefix followed by a keychain password item name or environment variable name.

Keychain example

 -p @keychain:<SECRET> uses the password stored in the keychain password item named <SECRET> and whose account value matches the user name specified.

Optionally, read the password from a keychain file by using the --keychain option.

Note: Because the user name can be inferred from the keychain password item, you may omit the username option when you use the -p @keychain: option.

Environment example

 -p @env:<SECRET> uses the value in the environment variable named <SECRET>.

--store-password-in-keychain-item

<name_for_keychain_item>

You want to create a keychain item using the name you specify, associate it with the account username, and store the password password in that keychain item. You can use this keychain item with the -p option to mask your password with other commands.

If a keychain item with the specified name and account already exists in the keychain, its password is updated. Otherwise, a new item is created with the specified name.

Create/store example

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

Stores the password in the keychain item named <MY_SECRET>

@keychain use example

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

Uses the password stored in the keychain password item named <MY_SECRET> and whose account value matches the user name specified.

Optionally, store the password in a keychain file by using the --keychain option.

Use the --sync option to create a password that is synchronized with your iCloud account.

--keychain<keychain_file>

Specify the path to a keychain file. Use --keychain with:

  • --store-password-in-keychain-item to store the password in the keychain file

  • -p @keychain: to read a password from the keychain file

Note: The --keychain option cannot be used with the --sync option.

--sync

Use --sync with --store-password-in-keychain-item to have the keychain item synchronized with your iCloud account and with other devices associated with the iCloud account.

Note: The --sync option cannot be used with the --keychain option.

--apiKey api_key

--apiIssuer issuer_id

Your API key and API issuer used for authentication. The apiKey / apiIssuer is required if you do not use username/password authentication. --apiIssuer is required if you specify --apiKey.

Note: In addition, you can specify the directory where your authentication key is located by using:

  • The environment variable $API_PRIVATE_KEYS_DIR

  • A user default API_PRIVATE_KEYS_DIR, as specified by this command line option: -API_PRIVATE_KEYS_DIR <directory>

--asc-public-id <public_id>

Required with --upload-package if your account is associated with multiple providers. You can use the --list-providers command to retrieve the providers associated with your account.

--apple-id <apple_id>

Required with --upload-package to specify the Apple ID of the app you are uploading.

--bundle-id <bundle_id>

Required with --upload-package to specify the CFBundleIdentifier of the app you are uploading.

--bundle-short-version-string <version_string>

Required with --upload-package to specify the CFBundleShortVersionString of the app you are uploading.

--bundle-version <bundle_version>

Required with --upload-package to specify the CFBundleVersion of the app you are uploading.

--output-format [xml | json | normal]

You want altool to return output in structured XML or json format, or unstructured text format (normal). By default, altool returns output information in text format.

Note: If you use an automated build system, you can integrate the notarization process into your existing build scripts. The altool and stapler command-line tools (included with Xcode) allow you to upload your software to the Apple notary service, and to staple the resulting ticket to your executable. altool is located here: /Applications/Xcode.app/Contents/Developer/usr/bin/altool

Upload and notarize your app binary files with altool

To notarize your app binary files, use Xcode v10.0 or later with the xcrun altool command. To learn more about notarization, read Notarizing Your App Before Distribution.

Note: All new apps signed or built after June 1, 2019 require notarization.

To run altool to upload and notarize your app, specify the following at the command-line in Terminal:

$ xcrun altool --notarize-app -f file --primary-bundle-id bundle_id -u username -p password

If successful, the UUID associated with the upload is returned, which you can use to retrieve information about the upload. The table below explains the parameters associated with notarization. The file path to the package, user name, password, and --primary-bundle-id are required. --asc-provider is required for an account associated with multiple providers.

Note: Notarization requires authentication, but you can pass in your credentials via Environment Variables or the keychain. See the -p parameter below. You can also create a keychain item to store your password for use with other commands.

Parameters

Description

--notarize-app

You want to upload the specified app file (.pkg, .dmg, or .zip) for notarization.

-f file

The path and filename for the app you are notarizing.

--primary-bundle-id bundle_id

The unique identifier of the app file you are notarizing. This option is required when using --notarize-app.

-u username

Your user name. Note that the username you specify is your App Store Connect user name.

-p password

Your user password. The password is required if you specify username. If you do not specify password on the command line, it will be read from stdin.

As an alternative to entering password in plaintext, you can also specify it using a @keychain: or @env: prefix followed by a keychain password item name or environment variable name.

Keychain example

-p @keychain:<SECRET> uses the password stored in the keychain password item named <SECRET> and whose account value matches the user name specified.

Optionally, read the password from a keychain file by using the --keychain option.

Note: Because the user name can be inferred from the keychain password item, you may omit the username option when you use the -p @keychain: option.

Environment example

-p @env:<SECRET> uses the value in the environment variable named <SECRET>.

--store-password-in-keychain-item

<name_for_keychain_item>

You want to create a keychain item using the name you specify, associate it with the account username, and store the password password in that keychain item. You can use this keychain item with the -p option to mask your password with other commands.

If a keychain item with the specified name and account already exists in the keychain, its password is updated. Otherwise, a new item is created with the specified name.

Create/store example

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

Stores the password in the keychain item named <MY_SECRET>

@keychain use example

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

Uses the password stored in the keychain password item named <MY_SECRET> and whose account value matches the user name specified.

Optionally, store the password in a keychain file by using the --keychain option.

Use the --sync option to create a password that is synchronized with your iCloud account.

--keychain<keychain_file>

Specify the path to a keychain file. Use --keychain with:

  • --store-password-in-keychain-item to store the password in the keychain file

  • -p @keychain: to read a password from the keychain file

Note: The --keychain option cannot be used with the --sync option.

--sync

Use --sync with --store-password-in-keychain-item to have the keychain item synchronized with your iCloud account and with other devices associated with the iCloud account.

Note: The --sync option cannot be used with the --keychain option.

--apiKey api_key

--apiIssuerissuer_id

Your API key and API issuer used for authentication. The apiKey / apiIssuer is required if you do not use username/password authentication. --apiIssuer is required if you specify --apiKey.

Note: In addition, you can specify the directory where your authentication key is located by using:

  • The environment variable $API_PRIVATE_KEYS_DIR

  • A user default API_PRIVATE_KEYS_DIR, as specified by this command line option: -API_PRIVATE_KEYS_DIR <directory>

--list-providers

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.

--asc-provider

<provider_shortname>

The provider’s shortname. Required with --notarize-app and --notarization-history if your user account is associated with multiple providers.

Note: If your user account is associated with multiple providers, you must provide at least one of the following: --asc-provider, --team-id, or --asc-public-id.

--asc-public-id  <public_id>

Required with --notarize-app and --notarization-history if your account is associated with multiple providers. You can use the --list-providers command to retrieve the providers associated with your account.

Note: If your user account is associated with multiple providers, you must provide at least one of the following: --asc-provider, --team-id, or --asc-public-id.

--team-id <wwdr_team_id>

Required with --notarize-app and --notarization-history if your account is associated with multiple providers. You can use the --list-providers command to retrieve the providers associated with your accounts.

Note: If your user account is associated with multiple providers, you must provide at least one of the following: --asc-provider, --team-id, or --asc-public-id.

Retrieve status and log files

You can retrieve the status and log file of an app previously uploaded for notarization using the specified uuid:

$ xcrun altool --notarization-info uuid -u username -p password

The above command returns the status and log file URL of the app with the specified UUID. Authentication is required.

Use the log file to check for any warnings or to see exactly what was included in your notarization ticket.

The possible statuses are:

  • Processing: The upload is successful and the app is being processed.

  • Upload failed: The upload failed.

  • Ready for distribution: The processing is complete and you can distribute the notarized app.

  • Rejected: The archive is invalid or failed security checks.

Retrieve notarization history

To retrieve a history of all the apps you’ve submitted for notarization:

$ xcrun altool --notarization-history page -u username -p password

The above command returns a list of all uploads submitted for notarization. The page parameter specifies a range of entries where 0 returns the most recent number of entries. A new page value will be returned that can be used as the page value to the next use of --notarization-history and so forth until no more items are returned. The user name and password are required. --asc-provider is required if your account is associated with multiple providers.

Distribute your content

After your app is notarized, Xcode creates a notarization ticket for the app that allows it to launch offline. You can use the xcrun stapler command-line tool to retrieve the ticket and attach it to the app. You can staple tickets directly to applications, disk images, and installer packages.

xcrun stapler staple <app bundle path>

After stapling the notarization ticket, you can distribute the content, and your users will get a notarized app.

Run other general commands

There are additional commands you can use with both standard app uploads and notarized app uploads. Use these commands to specify the transport method, upload speed, list options, and more.

Set transport method

The --transport command is optional and specifies the transport method used when uploading your bundle or app, or when notarizing your app. The available methods include: HTTPS, Aspera, or Signiant.

Note: You should only use this option when instructed by Apple.

Example of specifying the transport method:

$ xcrun altool --notarize-app -f file --primary-bundle-id bundle_id -u username -p password --transport HTTPS

Set throttle speed

The set throttle speed option allows you to limit the upload speed to the kilobits per second as noted in <Kbps> you specify. You can use either the -k or --throttle command to set throttle speed. These commands limit how much bandwidth the uploads use so that you will have more bandwidth for other processes if needed.

Note: You can specify --throttle or -k, but not both in the same delivery.

Parameters

Description

-k

Specifies the unit of transfer speed, or throttle speed, you want to use with Aspera’s FASP protocol, Signiant’s Media Exchange servers, or HTTPS. This option limits the upload speed to the number, in kilobits per second (Kbit/s), you specify.

This option is required when using the Aspera or Signiant delivery methods.

For Signiant, when you specify -k, Transporter converts the kilobits per second value to bytes per second.

For more precise delivery control, and to help diagnosis network congestion issues, Apple recommends specifying an initial setting of 100000, incrementing by 10000 as needed. For Aspera, you can specify a throttle speed up to 912,000 Kbit/s.

--throttle

Specifies the unit of transfer speed, or throttle speed, you want to use with Aspera’s FASP protocol, Signiant’s Media Exchange servers, or HTTPS. This option limits the upload speed to the number, in kilobits per second (Kbit/s), you specify. If you do not specify the throttle limit, the default limit is used, which may use more bandwidth than you want.

Example of specifying the throttle speed for HTTPS using --throttle:

$ xcrun altool --notarize-app -f file --primary-bundle-id bundle_id -u username -p password --transport HTTPS --throttle 1000

Generate lists

From the command line, you can generate a list of apps or providers associated with your account.

Use --list-apps to generate a list of all app records associated with your account(s). Authentication is required.

Example:

$ xcrun altool --list-apps --apiKey api_key --apiIssuer issuer_id

Use --list-providers to display a list of the providers associated with your account along with the short name and team ID. This command is useful to determine what short name to use with the --asc-provider option. Authentication is required.

Example:

$ xcrun altool --list-providers -u username -p password

Enable logging output

Use the --verbose command to show detailed information during operation of the current task. The resulting output log can help you troubleshoot any problems.

Example:

$ xcrun altool --notarize-app -f file --primary-bundle-id bundle_id -u username -p password --verbose

Show progress information

Use the --show-progress command to display information about altool activity, including a progress bar during file uploads.

Example:

$ xcrun altool -u username -p password --upload-app -f file_path --show-progress

View result codes

At the end of a command, you can use echo $? to view the success or failure result for the command. You’ll see a result code 0 for success or 1 for failure.

Failure example:

$ xcrun altool --notarize-app -f ~/Desktop/TestAppZip.zip --primary-bundle-id com.appleseed.test1 -u jappleseed -p ******* ;echo $?2020-05-18 10:05:08.051 altool[72994:16152114] *** Error: Unable to notarize app.2020-05-18 10:05:08.051 altool[72994:16152114] *** Error: code -43 (The file '/Users/jappleseed/Desktop/TestAppZip.zip' does not exist. Unable to upload your app for notarization.)1

Success example:

$ xcrun altool --notarize-app -f ~/Desktop/TestAppZip.zip --primary-bundle-id com.appleseed.test1 -u jappleseed -p ******* ;echo $?No errors uploading '/Users/jappleseed/Desktop/TestAppZip.zip'.RequestUUID = 7ada3865-9630-4c32-8ed5-f0f624cff6320

Glossary

Term

Definition

binary file

A file stored in computer-readable but not human-readable binary format. For altool, it’s the app file (.ipa or .pkg) you deliver to the App Store.

Invalid Binary

A state on App Store Connect indicating that your binary file was received through altool but does not meet all requirements for upload.

App Store Connect

A suite of web-based tools you can use to manage your apps. You use App Store Connect to submit and manage your apps for sale on the App Store, and to distribute beta versions of your app using TestFlight. You also use App Store Connect to accept legal agreements, to enter your tax and banking information, and to view trends and financial reports. For more information, see the App Store Connect Help.

metadata

Supplemental information about a media file type. For example, a file can contain information such as the name of the person that created the file, the length of the file, the title of the file, description, and so on.

notarization

A process developed by Apple to help identify and block malicious software prior to distribution. Notarization is not the same as validation. All new apps signed or built after June 1, 2019 require notarization.

SKU number

A unique ID you give to your app for internal tracking that is not visible to customers. The SKU can contain letters, numbers, hyphens, periods, and underscores but not start with a hyphen, period, or underscore. You can’t change the SKU after you add the app to your account.

validation

A process to determine whether your app meets minimum App Store requirements and ensure that it passes standard App Store Connect checks. Validation is not the same as notarization.

Revision history

This table describes the changes to Using altool.

Date

Notes

April 1, 2022

  • Added support for the --upload-package command

  • Deprecated the --upload-app command

  • Added support for the --apple-id, --bundle-id, --bundle-short-version-string, --bundle-version, --keychain, --show-progress, and --sync options

September 21, 2020

Added support for several new command line options. Added a note on using an app-specific password for two-factor authentication.

September 16, 2019

Apple introduces altool 1.1, a tool to help you submit your app binary files to App Store Connect for distribution on the App Store.