Getting Started with iMazing CLI

💡iMazing 3
This guide is for the legacy iMazing version 2. For information on version 3, please visit this page.

Starting from version 2.13.8, iMazing exposes a command line interface which grants direct access to core iMazing features. Whilst a few commands are available in trial mode for previewing purposes, the majority require an iMazing CLI license.

Documentation

Managing iOS devices effectively with iMazing's CLI requires a very good understanding of available commands and their behaviours. Please read the iMazing CLI Documentation (PDF download) carefully before proceeding.

Installation

Install iMazing if you haven't already. The CLI is integrated with the standard iMazing download.

Download and install iMazing on your Mac or PC computer.

Launching the CLI

On macOS, the executable is the same as iMazing's. Default location:

/Applications/iMazing.app/Contents/MacOS/iMazing

On Windows, the executable is different. Default location:

C:\Program Files\DigiDNA\iMazing\iMazing-CLI.exe

Trial

The following commands are fully available without a license:

*** Device Commands ***
--device-list
--device-list-not-paired
--device-list-all-connected
--device-list-cache
--device-pair
--device-forget
--device-info
--device-disk-usage
--device-console
--backup-device

*** License and Updates ***
--check-needs-update
--license
--remove-license

*** Cache ***
--remove-temp-folder
--remove-cache-folder

In order to use all the other commands, please purchase an iMazing CLI license from our store and enter your license code using the CLI's license command.

What to keep in mind

Listing devices and the importance of timeouts

Commands which do not apply to a specific device have a default timeout of sixty seconds. Try running this command:

./iMazing --device-list

iMazing will look for reachable devices, both via USB and Wi-Fi, during 60 seconds before returning the list. If you only want to list immediately available devices, use a shorter timeout:

./iMazing --device-list --timeout 1

Shared Settings

iMazing CLI offers a GUI free interface to iMazing. Consequently, iMazing settings configured in the GUI also apply when using the CLI, and vice-versa. The following default settings are particularly important:

1. Wi-Fi connection between the computer and the device can be enabled or disabled both with the GUI and with a CLI command. The setting resides iOS side and is hence persistent and shared. Important: by default, iMazing enables Wi-Fi for all newly connected devices (just after pairing). For security reasons, this is not the case if pairing is done by the CLI.
2. Backup location for newly connected devices is automatically set to the default backup location configured in iMazing's preferences.
3. Backup archiving is by default enabled, with 1 month of backup retention.

Use any and --usb wisely

Consider the following command:

./iMazing --device-erase --udid any --confirm

iMazing will begin looking for all available devices and send erase commands as connections are made. This means that ANY iOS or iPadOS device that's been paired and accepts Wi-Fi connections with the host may get erased. Not fun. To prevent catastrophes, use the --usb switch – it restricts commands to USB connected devices:

./iMazing --device-erase --usb --udid any --confirm

Don't forget the --pair and --activate switches

The command below outputs device information for all paired USB connected devices as they connect:

./iMazing --device-info --usb --udid any

Run the command and plug a device which hasn't yet been paired with the computer. You'll notice... nothing, iMazing simply ignores it. Now, add the --pair switch:

./iMazing --device-info --usb --udid any --pair

iMazing will now automatically try to pair new devices, and output a user interaction message if needed. Handy!

The --activate switch works the same way: if you connect a device that's new or recently erased, iMazing will automatically attempt to activate it before executing the command.