CFGUTIL(1)                BSD General Commands Manual               CFGUTIL(1)

     cfgutil -- Command-line iOS device management

     cfgutil [-C ] [-K ]
             [-e  | -f | --foreach]
             [--format JSON | plist | text] [-v] command [ ...]

     cfgutil performs various management tasks on one or more attached iOS
     devices. It can be used manually and as part of automated workflows.

     These terms are used throughout the manual and are useful for understand-
     ing the design of cfgutil.

             The first step of setting up a device after iOS is installed;
             requires an Internet connection. Some devices require a SIM card
             inserted to activate. If used, Activation Lock must be disabled.

     bundle identifier
             A unique name identifying an iOS app, generally in reverse DNS

             Example: `'

             A unique identifier of a device which is available even in recov-
             ery mode. Used to select devices.

     configuration profile
             A file containing settings for a device. The extension is

             A file containing an iOS app. The extension is .ipa.

             A file containing an iOS restore image. The extension is .ipsw.

     MobileSync directory
             The directory where backups are stored by iTunes and Apple Con-
             figurator 2:
                   ~/Library/Application Support/MobileSync/Backup

             Pairing a device requests it to trust the host Mac. Most commands
             require a paired device.

     provisioning profile
             A profile which allows development and enterprise apps to run on
             a device.  The extension is .mobileprovision.

     recovery mode/DFU
             A device showing the "connect to iTunes" screen or a black screen
             is in recovery mode. It can be repaired with revive or restore.

             A supervised device allows management of additional features
             which can otherwise only be modified on the device itself. Super-
             vised devices recognize host Mac computers through their supervi-
             sion identities. Unlike iOS devices, Apple TV devices always
             accept supervised-only commands, but don't use supervision iden-

     supervision identity
             A signing identity (X.509 certificate and private key) used to
             authenticate a host Mac to a supervised device. See EXAMPLES for
             steps to generate an identity.

             A key-value store on the device which can be used to save identi-
             fying information.

             Similar to ECID, a unique identifier for a device which is only
             available when booted into iOS.

     unlock token
             On supervised devices, a key which can be saved and later used to
             clear a passcode. This token must be saved before the device is
             locked, and may be invalidated if the device is erased or the iOS
             software is updated.

     Some options take a path to a file as a parameter for input or output.
     For these options, you may pass `-' to read the file from standard input,
     or write the results to standard output.

     IMPORTANT: If you use this for multiple options, the behavior is unde-

     Some options take passwords as parameters. Although the password can be
     entered directly, you can pass the name of a file by prefixing it with

     --password @password.txt

     You can also pass `-' and a password prompt will be shown. This avoids
     sensitive passwords being shown to other users.

             The certificate part of the supervision identity. Must be in DER

             The private key part of the supervision identity. Must be in DER

     -e | --ecid 
             Selects the device with that ECID on which to apply the given
             command. May be passed more than once to select multiple devices,
             although not all commands support this.

     -f | --foreach
             Selects all attached devices. If neither -e nor -f is passed, the
             first detected device will be selected.

             A few commands always operate on all attached devices, and a few
             commands will error if multiple devices are selected.

     --format JSON | plist | text
             Sets the output format of cfgutil.

             JSON and plist formats output dictionaries with results of each
             command; see JSON OUTPUT.

             Plaintext output format is the default.

             Output progress messages in JSON and plist format mode; other-
             wise, they will only ever print one message.

     -v      Increases the verbosity.

     More information on command options is available from `cfgutil help

             Activates devices which are unactivated and displaying the first
             page of Setup Assistant. Fails if the activation server requires
             user interaction, for example if the device is activation locked.

             This step runs as part of prepare.

     add-tags [-u  -n ]...
             Add a new tag to the device.  UUID and name can be any string.
             The name will be displayed in Apple Configurator 2, while the
             UUID will be used to uniquely identify the tag.

             Take a backup of a prepared iOS device and stores it under the
             device's UDID in the MobileSync directory. Backups may be taken
             from booted iOS devices which have completed Setup Assistant.

             Send an unlock token to a supervised device; the passcode will be
             removed from the device.  If there is a passcode policy set on
             the device, you may be required to immediately enter a new one.
             The unlock token path may be - to read from stdin.

             This command only runs on one device at a tine.

     erase | erase-content
             Causes a device to perform Erase All Content and Settings. All
             user data is removed and unrecoverable. The device must first be
             signed out of Find my iPhone. Although devices can also be erased
             by restoring new iOS firmware onto them, this method is much
             faster and does not require updating the OS.

             Devices running iOS 8 or earlier must be supervised to perform
             this action.

     exec [-a | --on-attach <shell command>] [-d | --on-detach <shell
             Run a custom command each time a device attaches or detaches.

             There is no filtering on device attach or detach events; for
             example, restoring a device will cause it to detach and attach
             several times in a row. Complex "on attach" scripts should be
             written to exit if a previous attach script is still running for
             the device.

             Script execution is not serialized. A detach script may start as
             an attach is still running and vice versa.

             The --ecid and --foreach global options aren't respected by this

             When the attach/detach scripts are running, these environment
             variables are set:
                   ECID          Target device's ECID.
                   PATH          The path is changed to include cfgutil.
                   UDID          Target device's UDID, if available.
                   deviceName    Target device's name, if available. ("iPhone
                   deviceType    Target device's type, if available.
                   buildVersion  Installed iOS build number, if available.
                                 Installed iOS version, if available.
                   locationID    Location ID of the device's USB port.

     get | get-property
             Fetch various properties of a device.

             To see the possible names of properties, use `cfgutil get

             To fetch all properties, use `cfgutil get all'.

             In JSON or plist mode, properties are printed as a dictionary
             under Output with ECIDs as keys and properties as values. Addi-
             tionally, if any errors occurred, Output will contain a dictio-
             nary under Error with ECIDs as keys and error descriptions as

             Some properties will be printed as dictionaries with specific
             keys. These include:


     get-app-icon [--raw] ...
             Save app icons from a single device.

             You can find the bundle identifier for an app with `cfgutil get

             Fetch the home screen layout of a single device and print it as a
             JSON object.

             The entries can be rearranged and used with set-icon-layout.  The
             first top-level entry represents the dock, while each later entry
             is one home screen page. Each page contains items that are either
             folders, web clip URLs, or app bundle identifiers. A folder is an
             array where the first entry is the name of the folder.

             Get unlock tokens from supervised devices, for later use by
             clear-passcode.  This command can't be used while the device is
             locked, so if you wish to clear passcodes from devices you must
             save the unlock token ahead of time. Unlock tokens may change,
             such as when the device is erased or updated.

             In plaintext mode, these are printed directly to Terminal.  JSON
             and plist mode print them per device under the Output key.

     help | usage 
             Show the help and options for a command.

             Installs the given app (IPA file or enterprise app) on devices.

             Users may need to sign into the App Store on the device with the
             appropriate account for the app to run.

     install-doc | install-document [-s | --sync] 
             Installs the given document(s) in the named app's storage on
             devices. Use the --sync option to sync the document(s) on the
             device using the given document(s) as a sync source. This will
             remove any documents on the device that are not included in the
             passed in documents. Any new source documents will be installed
             and any updated documents will also be updated on the device. Not
             passing this flag will reinstall non-iBooks documents even if an
             identical copy already exists on the device.

             You can find the bundle identifier for an app with `cfgutil get

     install-profile | ...
             Install the given configuration or provisioning profiles on
             devices.  Profiles will be installed silently if a supervision
             identity is passed in the general options.  On devices running
             iOS 8 or later, profiles are installed silently if the device is
             in Setup Assistant.

             Otherwise, profiles require confirmation on the device before
             installing.  When this occurs, cfgutil raises an issue and halts
             any further processes.  In this situation, it isn't possible to
             install multiple profiles in one cfgutil command.

             MDM enrollment profiles and profiles with SCEP payloads cannot be
             installed unless the device has already joined a network.
             cfgutil will automatically wait after installing configuration
             profiles containing networks to allow the device to auto-join.

             Some profiles can't be installed silently, such as profiles for
             email accounts if the password is missing. Some profiles can only
             be installed on supervised devices.

     list | list-devices
             List attached devices.  In plaintext output, the device type,
             ECID, UDID, USB location ID and name are printed in column format
             and can be parsed with a tool such as awk(1).  The --ecid and
             --foreach global options are not respected by this command. It
             always lists all devices.

             List backups available to be restored using restore-backup.

             These backups are stored in the MobileSync directory.

             Begin pairing with devices.

             If no supervision identity is passed, it is necessary to confirm
             pairing on the device itself by tapping Trust on the pairing dia-

             Applies initial configuration to freshly erased or unconfigured
             devices in Setup Assistant.  The devices are activated, have Set-
             up Assistant panes configured, and supervised, depending on the
             options passed.

             To supervise a device, use the --supervised , --name and
             --host-cert options.  If supervised, to never pair with another
             host Mac, use the --forbid-pairing option.  To use setup-time MDM
             enrollment on the device, use the --mdm-url and --anchor-cert

             Devices can also automatically skip some Setup Assistant panes.
             For specific skipping options, use `cfgutil help prepare'.

             In order to redo preparation on a device, it must be erased
             beforehand with erase (available with supervised devices),
             restore, or by using Erase All Content and Settings on the

             Devices enrolled in Apple School Manager or the Device Enrollment
             Program may be automatically configured using --dep.  In this
             mode, all non-ASM or non-DEP options have no effect, except for
             --skip-language and --skip-region.  Before preparing with ASM or
             DEP, the device must be able to reach your MDM server over a net-
             work connection. To cause devices to join a WLAN network, use
             install-profile before prepare to install a profile with a Wi-Fi
             payload set to auto-join. In this case, the "interactive install
             required" error from install-profile should be ignored.

             Removes the app with the given bundle identifier from attached

             Removes the passed-in configuration and provisioning profiles
             from devices. Parameters may either be the original files, by
             path, or the identifiers of the profiles.

     remove-tags ...
             Remove the tags with the given UUIDs from attached devices.

     rename | set-name 
             Set the name on attached devices to the given string.

             Immediately reboot attached devices. If a passcode is set on a
             device, it will not rejoin Wi-Fi networks or respond to commands,
             including clear-passcode until the passcode is entered.

     restore | update [-I ...]
             Install the latest iOS on attached devices. If a device is
             attached in recovery mode, both restore and update will erase it.

             If you want to install a beta build of iOS onto eligible devices,
             use one -I option for each IPSW file and the appropriate build
             will be used for each device.

             When using this option and targeting all devices, be sure only
             the intended devices are attached to the host Mac to avoid data
             loss. If a device signed into Find my iPhone is restored, you
             will have to clear its activation lock after restoring.

             Restore a backup of data and settings taken from a device.

             Some private data such as passwords will only be restored if the
             backup was encrypted with a password, or if the device targeted
             is the one who was the original source of the backup. Similarly,
             supervision state and configuration profiles are only restored to
             the original device. Note that using prepare to re-supervise
             devices will not work on the original device in this case, as it
             is already supervised.

             If --source is passed, each device will restore from the backup
             of that name in the MobileSync directory. Otherwise, each device
             will try to restore from the backup named with that device's

             Devices must be erased before a backup can be restored to them.

             Attempt to rescue a device which is in recovery mode. This com-
             mand attempts to install the latest iOS version on the devices
             without erasing user data. If the command fails, use restore to
             erase the device and make it usable again.

             Set or remove a password on the device which will be used to
             encrypt backups. When backups are passworded, more private infor-
             mation including account passwords can be restored onto any other
             device. Otherwise, private information will only be restored onto
             the original device from the backup.

             Removing the backup password requires the original password to be
             entered again, even if the device is supervised.

             Immediately power off attached iOS devices. This command does not
             support Apple TV.

             Set the home screen icon layout on devices, using the JSON format
             from get-icon-layout.

             Unexpected behavior may occur if the given layout does not con-
             tain every icon on the device or contains too many icons for one

             Display a single device's syslog output. This command runs until
             canceled with ctrl-C. If the device is detached, syslog waits for
             it to reattach.

             Remove the pairing to the host Mac from devices. After unpairing,
             most commands won't work on the device until its Trust pairing
             dialog is accepted.

             Show the currently installed version of cfgutil.

     wallpaper [--sourceRect ] [--screen lock | home | both] [--text
             Set wallpaper on supervised devices. You can use the options to
             crop the original image and overlay text on it.

     A new supervision identity can be generated using the openssl(1) command
     as follows:

           openssl genrsa -out tmp-privkey.pem 2048
           openssl req -new -x509 -key tmp-privkey.pem -out tmp-cert.pem -days
           openssl rsa -outform DER -out identity-key.der -in tmp-privkey.pem
           openssl x509 -outform DER -out identity-cert.crt -in tmp-cert.pem
           rm tmp-cert.pem tmp-privkey.pem

     You can export existing signing identities from Apple Configurator 2
     using Preferences > Organizations > Export Identity....

     In JSON and plist output modes, cfgutil's output is a dictionary similar
     to the following:


     All dictionaries have a key called Type, which can be used to determine
     the format of the message. Types are:

     CommandOutput   The command has succeeded and produced output.
                     Command  Name of the command.
                     Devices  List of ECIDs against which the command was run.
                     Output   A dictionary with ECIDs as keys and command-spe-
                              cific output as values. See COMMANDS for spe-
                              cific formats.

     Error           The command encountered an issue. See DIAGNOSTICS.
                     AffectedDevices    Devices which encountered this issue.
                     UnaffectedDevices  Devices which the command was running
                                        against, but were not affected by this
                                        issue. Their state is not known.
                     Message            High level description of the error.
                     Detail             Detailed description of the error.
                     FailureReason      Detailed failure reason of the error.
                     Domain / Code      Specific error code. Support documents
                                        will refer to errors using these.

     Syslog          Output from the syslog command.
                     Message  A line of text.

     When cfgutil encounters an issue, it stops the command immediately and
     reports which devices were affected by the issue. The state of unaffected
     devices is not guaranteed. After resolving the issue, check their state
     or repeat the command.

     In plaintext mode, error output looks like:

           $ cfgutil install-profile profile.mobileconfig
           cfgutil: error: A profile with the same identifier is already
           (Domain: ConfigurationUtilityKit.error Code: 118)

           "install-profile" failed on iPhone (ECID: 0x9118908BB6027).

           --- Summary ---
           Operation "install-profile" failed on 2 devices.

     In JSON or plist mode, cfgutil will output a message of type Error.

     The cfgutil utility exits 0 on success, and >0 if an error occurs.

     cfgutil was introduced with Apple Configurator 2.0.

     cfgutil doesn't support recovering from issues, while the GUI does.

Apple Configurator 2            11 August, 2015           Apple Configurator 2