CFGUTIL(1) BSD General Commands Manual CFGUTIL(1)
NAME
cfgutil -- Command-line iOS device management
SYNOPSIS
cfgutil [-C ] [-K ]
[-e | -f | --foreach]
[--format JSON | plist | text] [-v] command [ ...]
DESCRIPTION
cfgutil performs various management tasks on one or more attached iOS
devices. It can be used manually and as part of automated workflows.
TERMS
These terms are used throughout the manual and are useful for understand-
ing the design of cfgutil.
activation
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
format.
Example: `com.apple.Camera'
ECID
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
.mobileconfig.
IPA
A file containing an iOS app. The extension is .ipa.
IPSW
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
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.
supervision
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-
tities.
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.
tags
A key-value store on the device which can be used to save identi-
fying information.
UDID
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.
OPTIONS
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-
fined.
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.
-C
The certificate part of the supervision identity. Must be in DER
format.
-K
The private key part of the supervision identity. Must be in DER
format.
-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.
--progress
Output progress messages in JSON and plist format mode; other-
wise, they will only ever print one message.
-v Increases the verbosity.
COMMANDS
More information on command options is available from `cfgutil help
'.
activate
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.
backup
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.
clear-passcode
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
command>]
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
command.
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
1")
deviceType Target device's type, if available.
("iPhone7,2")
buildVersion Installed iOS build number, if available.
("12B466")
firmwareVersion
Installed iOS version, if available.
("8.1.3")
locationID Location ID of the device's USB port.
("0x00000001")
get | get-property
Fetch various properties of a device.
To see the possible names of properties, use `cfgutil get
supportedPropertyNames'.
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
values.
Some properties will be printed as dictionaries with specific
keys. These include:
configurationProfiles
provisioningProfiles
apps
tags
get-app-icon [--raw] ...
Save app icons from a single device.
You can find the bundle identifier for an app with `cfgutil get
apps'.
get-icon-layout
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-token
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.
install-app
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
apps'.
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
List backups available to be restored using restore-backup.
These backups are stored in the MobileSync directory.
pair
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-
log.
prepare
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
options.
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
device.
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.
remove-app
Removes the app with the given bundle identifier from attached
devices.
remove-profile
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.
restart
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-backup
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
UDID.
Devices must be erased before a backup can be restored to them.
revive
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-backup-password
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.
shut-down
Immediately power off attached iOS devices. This command does not
support Apple TV.
set-icon-layout
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
screen.
syslog
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.
unpair
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.
version
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.
GENERATING SUPERVISION IDENTITIES
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
3600
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....
JSON OUTPUT
In JSON and plist output modes, cfgutil's output is a dictionary similar
to the following:
{"Command":"add-tags","Type":"CommandOut-
put","Devices":["0x9118908BB6027"]]}
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.
DIAGNOSTICS
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
installed.
(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.
EXIT STATUS
The cfgutil utility exits 0 on success, and >0 if an error occurs.
HISTORY
cfgutil was introduced with Apple Configurator 2.0.
CAVEATS
cfgutil doesn't support recovering from issues, while the GUI does.
Apple Configurator 2 11 August, 2015 Apple Configurator 2