NAME

altool - Command-line tool for interacting with the App Store Connect API. For the legacy version of altool use 'man 7 altool'.

SYNOPSIS

Uploading and Validating Apps

xcrun altool [--upload-package | --upload-app -f] <file> --platform <{macos | ios | appletvos | visionos}> --provider-public-id <uuid> --apple-id <id> --bundle-id <id> --bundle-version <string> --bundle-short-version-string <string> [--wait] authentication [options]

xcrun altool --validate-app <file> --platform <{macos | ios | appletvos | visionos}> --provider-public-id <uuid> --apple-id <id> --bundle-id <id> --bundle-version <string> --bundle-short-version-string <string> authentication [options]

xcrun altool --build-status --delivery-id <uuid> --apple-id <id> --bundle-id <id> --bundle-version <string> --bundle-short-version-string <string> [--wait] authentication [options]

Listing Apps and Providers

xcrun altool --list-apps --provider-public-id <uuid> [{filters}] authentication [options]

xcrun altool --list-providers [--legacy] authentication [options]

Apple-Hosted Background Asset Pack Management

xcrun altool --upload-asset-pack <file> --apple-id <id> authentication [options]

xcrun altool --asset-pack-status [--asset-pack-version-id <uuid>| --apple-id <id> --asset-pack-identifier <string> --version <string>] authentication [options]

xcrun altool --list-asset-packs --apple-id <id> authentication [options]

xcrun altool --list-asset-pack-versions --apple-id <id> --asset-pack-identifier <string> authentication [options]

App Store Text Localization

xcrun altool --app-store-text <folder_path> [--upload | --download] --apple-id <id> --bundle-short-version-string <string> --platform <{macos | ios | appletvos | visionos}> authentication [options]

xcrun altool --beta-app-store-text <folder_path> [--upload | --download] --apple-id <id> --bundle-short-version-string <string> --platform <{macos | ios | appletvos | visionos}> authentication [options]

Managing Authentication

xcrun altool --store-password-in-keychain-item <keychain_item_name> --username <string> --app-password <string> [--keychain <file> | --sync]

xcrun altool --generate-jwt --api-key <string> --api-issuer <uuid> [--auth-string <string> | --p8-file-path <path>] [--keychain <file> | --sync]

DESCRIPTION

altool is a command-line tool that enables developers to automate interactions with the App Store Connect API. It provides functionalities for uploading app binaries, validating apps, managing app metadata, and listing available providers and applications. It streamlines the process of submitting and managing apps on the App Store. Authentication is required.

AUTHENTICATION

Authentication is required for most commands, using either username, app password and public provider ID or api key and api issuer.

-u, --username <string>

Username. Required for username/app-password authentication.

-p, --app-password <string>

App password. Required for username/app-password authentication. If not provided on the command line, it will be read from stdin. Alternatively, you can specify a keychain item or environment variable using the '@keychain:' or '@env:' prefix (e.g., '-p @keychain:MySecretPassword' or '-p @env:APPSTORE_PASSWORD').

--api-key <string>

API Key. Required for JWT authentication. This option expects a private key file named 'AuthKey_<string>.p8' to be located in one of the following directories: './private_keys', '~/private_keys', '~/.private_keys', '~/.appstoreconnect/private_keys', or the directory specified by the `API_PRIVATE_KEYS_DIR` environment variable or the `API_PRIVATE_KEYS_DIR` user default. You must first generate an API key in App Store Connect.

--api-issuer <uuid>

Issuer ID. Required for JWT authentication. You must obtain the issuer ID from App Store Connect when you create the API key.

--api-key-subject <{user}>

For individual JWT key the --api-key-subject should be set to 'user' when an --auth-string or p8 file name is not prefixed with ApiKey_.

--auth-string <string>

The private key within a JWT p8 file; the key string from after the line with 'BEGIN' to before the line with 'END'.

OPTIONS

--output-format {xml | json | normal}

Specifies the output format. `xml` and `json` provide structured output; `normal` (the default) provides unstructured output.

--show-progress

Displays a progress indicator during long-running operations.

--verbose

Enables verbose logging output, providing more detailed information about the command's execution. Useful for debugging.

--help

Displays this help message.

--use-old-altool

Uses the legacy version of `altool`. This may be necessary for compatibility with older systems or scripts. Newer commands not supported by old altool will still use new altool. Access to the man pages can be had using 'man 7 altool'.

COMMANDS

Uploading and Validating Apps

--upload-package <file>

Uploads the specified app archive to App Store Connect. Authentication is required. Can also be specified as --upload-app -f <file>

-t, --platform {macos | ios | appletvos | visionos}
Specifies the platform of the app archive.

--apple-id <id>
Specifies the Apple ID of the app.

--bundle-version <string>
Specifies the CFBundleVersion of the app package.

--bundle-short-version-string <string>
Specifies the CFBundleShortVersionString of the app package.

--provider-public-id <uuid>
Required when your account is associated with multiple providers and using username/app-password authentication. Specifies the provider's public ID.

Options:

--wait
Waits until the upload process is complete (status is PROCESSING) and returns the build status.

--validate-app <file>

Validates an app archive for the App Store without uploading it. This allows you to check for potential issues before submitting the app. Authentication is required.

-t, --platform {macos | ios | appletvos | visionos}
Specifies the platform of the app archive.

--apple-id <id>
Specifies the Apple ID of the app.

--bundle-version <string>
Specifies the CFBundleVersion of the app package.

--bundle-short-version-string <string>
Specifies the CFBundleShortVersionString of the app package.

--provider-public-id <uuid>
Required when your account is associated with multiple providers and using username/app-password authentication. Specifies the provider's public ID.

Listing Apps and Providers

--list-apps

Displays all apps associated with a provider. Authentication is required.

--provider-public-id <uuid>
Specifies the public ID of the provider whose apps should be listed.

Options:

--filter-apple-id <id>
Filters the list of apps by Apple ID.

--filter-bundle-id <id>
Filters the list of apps by bundle ID.

--filter-name <app_name>
Filters the list of apps by name.

--filter-sku <sku>
Filters the list of apps by SKU.

--filter-platform {macos | ios | appletvos | visionos}
Filters the list of apps by platform.

--list-providers

Displays a list of the providers and their attributes associated with your account.

-u, --username <string>

Username.

-p, --app-password <string> App password.

Options:

--legacy
Outputs provider information in a format that older versions of `altool` used.

Managing App Store Text

--app-store-text <folder_path> [--upload ]

Allows you to download the App Store Text localizations. These can then be edited and re uploaded. See the Readme that is provided with the download for detailed instructions. Authentication is required.

--apple-id <id>
Specifies the Apple ID of the app.

--bundle-short-version-string <string>
Specifies the CFBundleShortVersionString of the app.

-t, --platform {macos | ios | appletvos | visionos}
Specifies the platform of the app.

--beta-app-store-text <folder_path> [--upload ]

Allows you to download the App Store Text for beta testing. These can then be edited and re uploaded. See the Readme that is provided with the download for detailed instructions. Authentication is required.

--apple-id <id>
Specifies the Apple ID of the app.

--bundle-short-version-string <string>
Specifies the CFBundleShortVersionString of the app.

-t, --platform {macos | ios | appletvos | visionos}
Specifies the platform of the app.

Apple-Hosted Background Asset Pack Management

--upload-asset-pack <file>

Uploads the specified asset pack to App Store Connect.

--apple-id <id>
Specifies the Apple ID of the app to which the asset pack will be associated.

Options:

--wait
Waits until the asset pack processing is complete (status is READY, FAILED, or NULL) and returns the status.

--asset-pack-status

Returns the status of the asset pack.

--asset-pack-version-id <uuid>
The UUID of the asset pack version.

--apple-id <id>
The Apple ID of the app associated with the asset pack.

--asset-pack-identifier <string>
The developer-defined name of the asset pack.

--version <string>
The version number of the asset pack app version.

--list-asset-packs

Returns a list of asset packs.

--apple-id <id>
Specifies the Apple ID of the app associated with the asset packs.

--list-asset-pack-versions

Returns a list of asset pack versions.

--apple-id <id>
Specifies the Apple ID of the app associated with the asset pack.

--asset-pack-identifier <string>
Specifies the developer-defined name of the asset pack.

Managing Authentication

--store-password-in-keychain-item <keychain_item_name>

-u, --username <string>

Username.

-p, --app-password <string>

App password.

Stores the password in the keychain item named <keychain_item_name> associated with the account.

Options:

--keychain <filename>
Used with --store-password-in-keychain and the @keychain: option for --app-password 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.

--sync
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.

--generate-jwt

Generates a JSON Web Token (JWT) for authentication. JWT authentication is the preferred method for automated access to the App Store Connect API.

Options:

--auth-string <string>
The private key within a JWT p8 file; the key string from after the line with 'BEGIN' to before the line with 'END'.

Build Status

--build-status

Returns the status of the delivery in the import process and App Store Connect flow.

--delivery-id <uuid>
The delivery UUID of the app. This value is returned after a successful --upload-package.

--apple-id <id>
Specifies the Apple ID of the app.

--bundle-version <string>
Specifies the CFBundleVersion of the app.

--bundle-short-version-string <string>
Specifies the CFBundleShortVersionString of the app.

App Settings

--app-settings

Return the app settings for this app.

AUTHENTICATION

Most commands require authentication to access your account and perform actions on App Store Connect. JWT authentication using API keys is the preferred method.

-u, --username <string> Username. Required for username/app-password authentication.

-p, --app-password <string> Password. Required if username specified. If this argument is not supplied on the command line, it will be read from stdin. Alternatively to entering <string> in plaintext, it may also be specified using a '@keychain:' or '@env:' prefix. Example: '-p @keychain:<name>' uses the password stored in the keychain password item named <name>. Note also that the --username can be inferred from the keychain item so --username can be omitted when using a '-p @keychain:' option. Example: '-p @env:<variable>' uses the value in the environment variable named <variable>.

--api-key <string> ApiKey. Required for JWT authentication (in lieu of username/app-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 environment variable $API_PRIVATE_KEYS_DIR or a user default API_PRIVATE_KEYS_DIR to specify the directory where your AuthKey file is located. Individual JWT keys are in the form 'ApiKey_<api_key>.p8'.

--api-issuer <uuid> Issuer ID. Required if --api-key is specified.

EXAMPLES

Upload an app package using username/app-password authentication:

xcrun altool --upload-package MyApp.ipa --platform ios --provider-public-id 12345678-1234-1234-1234-123456789012 --username myusername --app-password mypassword

Upload an app package using JWT authentication:

xcrun altool --upload-package MyApp.ipa --platform ios --apple-id com.example.myapp --api-key MY_API_KEY --api-issuer 12345678-1234-1234-1234-123456789012

Validate an app:

xcrun altool --validate-app MyApp.ipa --username myusername --app-password mypassword

Upload Apple-Hosted Background Asset Pack:

xcrun altool --upload-asset-pack MyAssetPack.aar --apple-id 1234567890 --api-key MY_API_KEY --api-issuer 12345678-1234-1234-1234-123456789012

Apple-Hosted Background Asset Pack Status:

xcrun altool --asset-pack-status --asset-pack-version-id 12345678-1234-1234-1234-123456789012 --api-key MY_API_KEY --api-issuer 12345678-1234-1234-1234-123456789012

List providers:

xcrun altool --list-providers --username myusername --password mypassword

Store password in keychain:

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

List apps filtered by platform:

xcrun altool --list-apps --provider-public-id 12345678-1234-1234-1234-123456789012 --filter-platform ios --username myusername --app-password mypassword

DIAGNOSTICS

If xcrun altool fails, it will typically print an error message to stderr and exit with a non-zero status. Common error messages include:

"Authentication failed"

Indicates that the provided username/app-password or API key/issuer ID are invalid. Double-check your credentials.

"Invalid parameter"

Indicates that one or more of the command-line options are invalid or missing. Review the command syntax and required options.

BUGS

No known bugs.

AUTHOR

Apple Inc.

HISTORY

xcrun altool was first introduced as a command-line tool for interacting with the iTunes Connect API. It has been updated over time to support new features and the App Store Connect API.