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.
- -u, --username
username
- Username. Required to connect for most commands. You must also specify
--password.
- -p, --password
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
api_key
- 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.
- --apiIssuer
issuer_id
- Issuer ID. Required if --apiKey is specified.
Keychain Usage
- --store-password-in-keychain-item
name_for_keychain_item -u username -p
password
- 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 [...]
- --keychain
path_to_keychain_file
- 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.
- --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.
General
- -f, --file
file
- file specifies the path to the file to process.
- -t, --type {macos | ios |
appletvos}
- Specify the platform of the file.
- --transport
{HTTPS | Signiant | Aspera | DAV}
- 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.
- -k, --throttle
Kbps
- Allows you to limit the upload speed to Kbps kilobits per second.
If not specified, then the default limit is used.
- --apple-id
id
- Specify the Apple ID of the app to be uploaded with
--upload-package.
- --bundle-id
id
- Specify the CFBundleIdentifier of the app to be uploaded with
--upload-package.
- --bundle-short-version-string
string
- Specify the CFBundleShortVersionString of the app to be uploaded with
--upload-package.
- --bundle-version
id
- Specify the CFBundleVersion of the app to be uploaded with
--upload-package.
- --product-id
id
- Specify the product ID of the hosted content package to be uploaded with
--upload-hosted-content.
- --sku sku
- Specify the SKU of the hosting app associated with the hosted content to
be uploaded with --upload-hosted-content.
- --asc-provider
provider_shortname
- 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.
- --asc-public-id
public_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.
- --team-id
wwdr_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.
- --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.
- --output-format
{xml | json | normal}
- 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
- Show progress during operation.
- --verbose
- Enable logging output. Show detailed information during operation.
- -h, --help
- Display the help page.
App Store Apps
- --upload-package
file_path
- 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.
- -v, --validate-app
- 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.
- --upload-app
[DEPRECATED use --upload-package instead]
- 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.
- --upload-hosted-content
file_path
- Uploads the specified hosted content in-app purchase archive to the App
Store. --sku, --type, --product-id,
--asc-provider, and Authentication are required.
- --list-apps
- Returns a list of all app records associated with your account(s).
Authentication is required.
Notarizing Apps
- --notarize-app
- 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.
- --notarization-info
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'.
- --notarization-history
page
- 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.
- --primary-bundle-id
bundle_id
- 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.