Upload and manage your assets in the iTunes Store using the iTunes Store’s Transporter (iTMSTransporter).



Upload and manage your assets in the iTunes Store using the iTunes Store's Transporter (iTMSTransporter).


require "itunes/store/transporter"

itms = iTunes::Store::Transporter.new(:username => "SomeUser",
                                      :shortname => "shrt",
                                      :password => "w3c@llYoU!")

metadata = itms.lookup(:apple_id => "yourpackage")

  itms.verify("/path/to/package2.itmsp", :verify_asssets => false)
rescue iTunes::Store::Transporter::ExecutionError => e
  puts "Exited with #{e.exitstatus}"

  e.errors.each do |error|
    puts "#{error.message} - #{error.code}"
    puts "Basically, you have some faulty metadata" if error.missing_data?


iTunes::Store::Transporter is a wrapper around Apple's iTMSTransporter program. It currently supports the following operations:

  • Upload packages

  • Validate packages

  • Retrieve status information

  • Lookup package metadata and video assets

  • List providers

  • Retrieve iTunes metadata schemas

It also includes itms, an executable that's sorta like using iTMSTransporter directly except that it can send email notifications and allows one to set global/per-command defaults via $HOME/.itms.


Locating iTMSTransporter

If the iTMSTransporter cannot be found in one your platform’s known locations you must specify it when creating an instance of iTunes::Store::Transporter via the :path option.

If you're using the bundled itms command you must use its --path option or specify the path in the itms config file. See the itms section for more info.

Running on Windows

On Windows iTMSTransporter is called via the iTMSTransporter.CMD batch file. This file does not handle the iTMSTransporter's exit status correctly, causing iTunes::Store::Transporter to report everything as a success.

This can be fixed by modifying iTMSTransporter.CMD (note that the following does not mimic the batch file exactly):


call iTMSTransporter\iTMSTransporter %*

REM Add this line:
set exited=%errorlevel%

cd %olddir%

REM Add this line too:
exit /b %exited%

Using itms


  • COMMAND - The command to run, which can be any one of the iTunes::Store::Transporter methods

  • OPTIONS - These are quivalent to the given COMMAND's options except they must be given in a strict long option format. For example :apple_id => "X123" would be --apple-id=X123. Boolean options can be negated with the --no- prefix. For more info see each command’s options.

  • PACKAGE - The package or directory to operate on, if required by the command

Note that options with a value must contain the equals character ("="). The format is --option=value and not --option value.


itms upload --username=sshaw --password=w3cAllYoU --transport=aspera a_package.itmsp
itms version
itms status --no-print-stderr --vendor-id=X123123 --username=sshaw --password=sekr3t_ --shortname=ss

Username, Password, Short Name

Most all commands require your username and password, some require a shortname. These can be specified on the command line via the --username, --password, and --shortname options, or via an itms config file. See the config file section below.

Lookup command

The lookup command differs slightly from the gem by allowing you to download low-quality copies of the assets associated with the looked up metadata. These assets are created by Apple (at the time of this writing, Apple only allows you to download full and preview assets, there is nothing in itms that would prevent you from downloading other types of assets if/when they're supported).

For example, to lookup the metadata for package X123 and download low-quality copies of all the assets:

itms lookup --vendor-id=X123 --assets

To download a particular asset type just provide its name:

itms lookup --vendor-id=X123 --assets=preview

If there are multiple territories this will download the preview assets for each of them. To only download assets in a given territory or territories use:

itms lookup --vendor-id=X123 --assets=preview:US
itms lookup --vendor-id=X123 --assets=preview:US:BR

If necessary multiple asset types can be seperated by a comma:

itms lookup --vendor-id=X123 --assets=full,preview
itms lookup --vendor-id=X123 --assets=full,preview:MX

Config file

Default options and email notifications can be placed in a YAML file at $HOME/.itms. To skip loading the config file use the --no-config option.

# Global command defaults
path: /usr/bin
username: sshaw
password: Pa55W0rd!

# Global email defaults
  to: everyone@example.com
  from: no-reply@example.com
  host: smtp.example.com

# Verify command
  shortname: lUzer

# Upload command
  shortname: enc0d3rz
  transport: Aspera
  rate: 750000
  # Email notifications for the upload command
      cc: assets@example.com
      subject: iTunes Upload <%= @apple_id %>
      message: |
        <%= @username %> uploaded it using <%= @transport %>

      to: support@example.com
      subject: Upload Failed!
      message: |
        Here's the problem:

        <%= @error %>

        Fix it!

As you can see, command options are turned into template variables.

More Info


Skye Shaw [skye.shaw AT gmail.com]


Released under the MIT License: www.opensource.org/licenses/MIT