Commands

iOS Target Manipulation

All idb cli commands run against a specific iOS Target (Simulator or Device). Since a single host will almost certainly have more than one target attached, there needs to be a way of specifying which iOS Target to run the command against.

The common denominator of all iOS Targets is the presence of a UDID. This is a identifier unique to each target. iOS Simulators have UDIDs based on NSUUID, for Devices it depends on the phone model, but the iPhone Wiki has an overview of the formats. As far as idb is concerned, a UDID is just a string.

The idb cli is powered by the idb_companion, to perform all underlying behaviour. Since an idb_companion can be exposed over a domain socket or TCP socket, it's also possible to address a companion directly, instead of addressing via UDID.

Running commands against a specific iOS Target

idb maintains local state of iOS Targets that it is aware of. This state can be modified or bypassed. The idb leans heavily on the idb_companion in order to process requests. As such all commands that manipulate iOS Targets requires a companion to service them.

If you can pass the location of the companion in each call, then there is no need to modify this internal state. All idb commands can be prefixed with the IDB_COMPANION environment variable, which will directly address a given companion. If the companion location is known ahead of time (instead of just a UDID), this is the preferred way of addressing an iOS target:

# Run a describe command against a companion running on the loopback interface
# on TCP Port 10882
$ IDB_COMPANION=localhost:10882 idb describe
# This can also be a path to a domain socket that the companion is running on
$ IDB_COMPANION=/tmp/idb_companion_domain_sock idb describe

Addressing via a UDID instead of the companion address is achieved by connecting a companion, so that this knowledge persists over invocations:

# Connecting via a TCP companion server
idb connect COMPANION_HOST COMPANION_PORT
SOME_UDID
# Connecting via a unix domain socket
idb connect COMPANION_DOMAIN_SOCKET_PATH
SOME_UDID
# SOME_UDID can then be used to address the connected target via --udid

idb can also transparently start companions in the background, so the user does not need to be aware of how to start a companion or address it directly:

# This will implictly start a companion in the background and keep it alive
$ idb connect TARGET_UDID
TARGET_UDID

Using connect is also optional; when a command is executed against a given UDID and a companion is not running for the given UDID, a companion will be started in the background in a similar way to idb connect:

# When TARGET_UDID does not have a companion running for it, running describe will run it in the background.
$ idb describe --udid TARGET_UDID

Disconnect a target

idb disconnect COMPANION_HOST COMPANION_PORT
idb disconnect TARGET_UDID

The opposite of connect. This will not terminate the companion backing this target

List connected targets

idb is aware of the companions that you have manually connected, as well as other iOS targets that do not yet have companions. This can be shown with list-targets:

idb list-targets

The output will show which targets do and don't have companions associated with them.

Boot a simulator

idb boot UDID

This will only apply to iOS Simulators.

Simulator lifecycle

The remaining lifecycle commands also apply to iOS Simulators only, and only when idb is running on macOS.

# Create a simulator from a device type and an OS version, printing the new UDID
idb create "iPhone 15" "iOS 17.0"
# Shut a booted simulator down
idb shutdown UDID
# Erase a simulator's contents and settings
idb erase UDID
# Clone a simulator, printing the new UDID
idb clone UDID
# Delete a simulator, or every simulator in the set
idb delete UDID
idb delete-all

Each of these takes the UDID as an optional positional argument, falling back to the IDB_UDID environment variable.

Describe a target

idb describe

Returns metadata about the specified target, including:

UDID
Name
Screen dimensions and density
State (booted/...)
Type (simulator/device)
iOS version
Architecture
Information about its companion

General arguments

In addition to arguments that are relevant to specific commands, there are other optional arguments that apply to all commands.

Argument	Description	Default
`--udid UDID`	UDID of the target. Can also be set with the `IDB_UDID` environment variable	If only one target is connected it'll use that one
`--json`	JSON structured output where applicable	`False`
`--reason REASON`	A free-form note describing why the command was run	None

A second set of arguments configures the idb cli itself rather than the command being run, so they are placed before the command name:

Argument	Description	Default
`--log {DEBUG,INFO,WARNING,ERROR,CRITICAL}`	Set the log level	`WARNING`
`--companion HOSTNAME:PORT`	Address a companion directly instead of via a UDID. Can also be set with the `IDB_COMPANION` environment variable	Resolved from local state
`--companion-path PATH`	Path to the `idb_companion` binary used for companions that `idb` starts itself. macOS only	The `idb_companion` found on the host
`--companion-tls`	Connect to the companion over TLS. Can also be set with the `IDB_COMPANION_TLS` environment variable	`False`
`--compression ALGORITHM`	Compression algorithm for payloads sent to the companion. The decompressor must be available where the companion runs	`GZIP`
`--no-prune-dead-companion`	Leave local state alone when a companion is found to be unresponsive, instead of forgetting it	Prunes

$ idb --log DEBUG describe --udid TARGET_UDID

Apps

List apps

idb list-apps

Lists the targets installed applications and their metadata, including:

Bundle ID
Name
Install type (user, system)
Architectures
Running status
Debuggable status

Install an app

idb install /path/to/testApp.app

Installs the given .app or .ipa. The app target architecture should match that of the target.

Launch an app

idb launch com.apple.Maps

Any environment variables that are prefixed with IDB_ will be set on the launched app, with that prefix removed.

Custom launch arguments can also be provided by appending them to the end of the command.

By default idb launch will fail if the app is already running, this can be overruled with -f/--foreground-if-running.

To tail the output of the launched process, provide the -w/--wait-for flag. The stdout and stderr of the app will be streamed back until the app exits. When running in this mode, the app will be killed when sending a SIGTERM to the idb cli, for example with ^C in a shell.

Kill a running app

idb terminate com.apple.Maps

Kills an app with the given Bundle ID. If the app is not running, or there is no app installed for the given Bundle ID, this will fail

Uninstalling an app

idb uninstall com.foo.bar

Removes an app from the target by Bundle ID.

Tests

idb exposes test execution primitives via binaries and has a number of modes of operation. Go here for more details about how idb approaches Test Execution.

Install a test bundle

idb xctest install testApp.app/Plugins/testAppTests.xctest

Before a test can be run through idb it must first be installed on the target. This performs a "relocation" process, so that the test bundle can be invoked multiple times in different modes of execution.

Both .xctest and .xctestrun files can be installed with this command.

List installed tests

idb xctest list

Lists all of the tests installed on a target.

List tests inside a bundle

idb xctest list-bundle com.facebook.myAppTests

Lists all of the individual tests inside a test bundle. This will load the test bundle in the target's runtime and discover all of the tests that can be executed.

Running tests

Environment variables that are prefixed with IDB_ will be passed through to the test run with that prefix removed, also any arguments appended to the end of the idb command will be supplied as arguments to the test run.

Please consult the Test Execution section for understanding more about the various modes that are available for running tests

File commands

The idb file commands allow for managing manipulating files on a target. File operations are applied to "containers", which allow manipulation of different iOS subsystems. File commands are documented within the File Containers section.

Debug an app

Starting a debug session

idb debugserver start BUNDLE_ID

Starts a debug session. The output will be similar to process connect connect://localhost:10881 and it will be used to start the lldb. In another terminal, type in the command lldb, which will start the lldb. There, type the output of the start command to connect the debug server.

Stop a debug session

idb debugserver stop

Stops a running debug session.

Information about a debug session

idb debugserver status

Display metadata about any running debug sessions.

Debug Adapter Protocol

idb dap /path/to/dap_package

Installs a Debug Adapter Protocol package on the target and spawns a debug server speaking it, relaying the protocol over stdin and stdout. This is what an editor or IDE attaches to, rather than something you would usually run by hand.

UI Automation

The idb ui command group reads the screen through the target's accessibility system, acts on the elements it reports, and synthesizes HID events. It has a page of its own: UI Automation documents the whole group, and Accessibility covers the backends that serve a read and the formats a read comes back in.

# Read the screen
idb ui describe-all
idb ui describe-point X Y
idb ui describe MARKER
# Act on an element, by coordinate or by accessibility marker
idb ui tap X Y
idb ui tap MARKER
idb ui scroll down
idb ui set-value MARKER --value VALUE
# Synthesize input
idb ui swipe X_START Y_START X_END Y_END
idb ui button {APPLE_PAY,HOME,LOCK,SIDE_BUTTON,SIRI}
idb ui text "some text"
idb ui key 4

Misc

Reset Idb

idb kill

idb stores information about available companions in a local file. this command clears these files and kills the idb notifier if one is running.

Focus a simulators window

idb focus

Brings a simulators window to the foreground.

Install a .dylib

idb dylib install test.dylib

Installs a .dylib on the target. This can then be injected into apps on launch.

Install a .framework

idb framework install My.framework

Installs a .framework bundle on the target, for a binary that expects to link against it at runtime.

Install debug symbols

idb dsym install MyApp.app.dSYM
# Or place them inside an installed app's container
idb dsym install MyApp.app.dSYM --bundle-id com.foo.bar

Installs a dSYM bundle so that backtraces from the target symbolicate. With --bundle-id the symbols are written inside that app's container instead of alongside the target's other symbols.

Instruments

idb instruments TEMPLATE

Starts instruments running connected to the target

Record a trace

idb xctrace record --template 'Time Profiler' --all-processes --output out.trace
idb xctrace record --template 'Time Profiler' --launch com.foo.bar --time-limit 30s

Records an Instruments trace on the target and writes the .trace bundle back to the host, mirroring the options of xctrace record. Exactly one of --all-processes, --attach <pid|name> or --launch <command> selects what is recorded, and --template is required. --time-limit bounds the recording; otherwise it runs until ^C. Environment variables prefixed with IDB_ are passed through to a launched process with that prefix removed, as they are for idb launch.

Take a screenshot

idb screenshot OUTPUT_PNG
# Or write the image to stdout
idb screenshot -

Captures the target's screen as a PNG.

Record a video

idb video OUTPUT_MP4

Starts recording the target's screen, outputting the content to the specified path. The recording can be stopped by pressing ^C. idb record video OUTPUT_MP4 is an equivalent, older spelling of the same command.

Stream video

# Stream H264 to a file
idb video-stream OUTPUT_FILE
# Stream MJPEG to stdout at a fixed framerate
idb video-stream --format mjpeg --fps 30

Streams the target's screen as it is encoded, rather than writing a single file at the end. With no output file the stream is written to stdout, so it can be piped into another process. --format is one of h264, rbga, mjpeg or minicap, --fps fixes the framerate (dynamic by default), and --compression-quality and --scale-factor (each between 0 and 1.0) trade image quality for bandwidth.

Log

idb log

Tail logs from a target, uses the standard log(1) stream arguments

Companion log

idb companion log

Tails the log of the companion backing the target, rather than the log of the target itself. This is the first place to look when a command fails for a reason the client cannot see.

Open a url

idb open https://facebook.com

Opens the specified URL on the target. This works both with web addresses and URL schemes present on the target.

Send a push notification

idb send-notification com.apple.Maps '{"aps": {"alert": "Hello"}}'

Delivers a push notification payload to an installed app, without any of the certificate or network setup a real push would need. The payload is the JSON that the app would have received from APNs.

Simulate a memory warning

idb simulate-memory-warning

Delivers a memory warning to the target, so an app's response to memory pressure can be exercised on demand.

Clear the keychain

idb clear-keychain

For simulators idb can clear the entire keychain.

Set a simulators location

idb set-location LAT LONG

Overrides a simulators location to the latitude, longitude pair specified.

Read and write preferences

# Read a preference from the global domain
idb get AppleLanguages
# Read from a specific domain
idb get --domain com.apple.Accessibility ApplicationAccessibilityEnabled
# Write a preference, with an explicit value type
idb set --domain com.apple.Accessibility ApplicationAccessibilityEnabled --type bool true

Reads and writes the target's preferences, in the same way defaults(1) does on macOS. --domain defaults to the Apple Global Domain, and --type defaults to string; the supported types are those defaults itself accepts. Most apps read their preferences at launch, so relaunch after writing one.

idb list locale

Lists the locale identifiers the target supports, which is where the value for a locale preference comes from.

Add media

idb add-media cat.jpg dog.mov

Files supplied to this command will be placed in the targets camera roll. Most common image and video file formats are supported.

Clear the photo library

idb photos clear

Empties the target's camera roll, undoing an add-media and returning a simulator to a known state between runs.

Approve and revoke permissions

idb approve com.apple.Maps photos camera
idb revoke com.apple.Maps photos camera

For simulators idb can programmatically grant or withdraw an app's permissions, so a permission prompt never has to be dismissed by hand. Both commands take one or more of:

photos - Permission to view the camera roll
camera - Permission to access the camera
contacts - Permission to access the targets contacts
location - Permission to access the targets location
microphone - Permission to record audio
notification - Permission to deliver notifications
url - Permission to open a URL scheme. Requires --scheme naming the scheme in question

Add contacts

idb contacts update db.sqlite

For simulators idb can overwrite the simulators contacts db.

idb contacts clear

Empties the contacts database instead of replacing it.

Interactive shell

idb shell

Opens a prompt that accepts idb commands one after another, holding the connection to the companion open between them. This is a shell for idb itself, not a shell on the target — it saves the per-command startup and connection cost when running a sequence of commands by hand.

Crash logs

idb includes several commands for fetching and managing a targets crash logs.

List crash logs

idb crash list

Fetches a list of crash logs present on the target. The results can be filtered by providing --before/--since/--bundle-id.

Fetch a crash log

idb crash show CRASH_NAME

Fetches the crash log with the specified name

Delete crash logs

idb crash delete CRASH_NAME
idb crash delete --before/--since/--all X

Deletes crash logs, either specified by name or all those matching the provided filters --before/--since/--bundle-id/--all.

Companion Commands

The idb_companion is a native Objective-C++ executable that is used to manipulate iOS Simulators & Devices. It implements many of the CRUD-style operations associated with iOS resources and exposes a gRPC interface that can be consumed by the idb client.

When using idb for ad-hoc usage, you likely won't need to use the idb_companion cli directly as it's wrapped by the idb cli. However, it can be used directly if needed.

Starting a `gRPC` Server

To start a companion server for an iOS Simulator or Device that you have running on your machine:

idb_companion --udid UDID

The companion server will be started for the given UDID. If the given UDID cannot be found, the companion launch will fail. UDIDs have different formats and the companion will parse it in order to find the appropriate target.

There are a number of additional switches for altering companion behaviour. These are documented via idb_companion --help and can also be seen in the table below:

Argument	Description	Default
`--udid UDID`	Specify the target device / simulator. `mac` runs a companion for the host itself, `only` for the sole target available
`--grpc-port PORT`	The TCP port to start the `gRPC` Server on	`10882`
`--grpc-domain-sock PATH`	Unix domain socket path to serve on. Supersedes `--grpc-port`	Binds TCP
`--tls-cert-path PATH`	Serve over a TLS enabled socket, using this certificate	No TLS
`--log-file-path PATH`	Path to write companion logs to	Will log to `stderr`
`--log-level info\|debug`	How much the companion logs	`debug`
`--device-set-path PATH`	iOS Simulator custom device set path	`~/Library/Developer/CoreSimulator/Devices`
`--only simulator\|device\|ecid:ECID`	Limit the companion to a subset of the available targets	All targets
`--headless VALUE`	Tie the simulator boot's lifecycle to this invocation, so shutting the companion down shuts the simulator down	`false`
`--terminate-offline VALUE`	Exit when the target goes offline, instead of staying alive	Stays alive
`--idle-shutdown-time SECS`	Exit after this many seconds with no active or newly received `gRPC` requests	Stays alive

When using the idb cli directly on iOS targets local to your Mac you won't need to start companions manually. However, it can be handy to use this for debugging or manually managing companions. You might wish to manually manage companions when exposing a companion over the network to another machine, or if you have an Application built on top of idb where you wish to precisely control the lifecycle of the companion and it's logs.

Starting a notifier

The companion can operate in "notifier" mode. This means that all changes in Device & Simulator availability are written out. This is useful for discovering the state of Simulators & Devices over time.

idb_companion --notify FILE_PATH|stdout

It's also used as an implementation detail of how the idb cli discovers what targets it can connect to, when the idb cli is run on macOS.

If stdout is provided, updates will be written to stdout instead of the provided file path.

iOS Target Manipulation​

Running commands against a specific iOS Target​

Disconnect a target​

List connected targets​

Boot a simulator​

Simulator lifecycle​

Describe a target​

General arguments​

Apps​

List apps​

Install an app​

Launch an app​

Kill a running app​

Uninstalling an app​

Tests​

Install a test bundle​

List installed tests​

List tests inside a bundle​

Running tests​

File commands​

Debug an app​

Starting a debug session​

Stop a debug session​

Information about a debug session​

Debug Adapter Protocol​

UI Automation​

Misc​

Reset Idb​

Focus a simulators window​

Install a .dylib​

Install a .framework​

Install debug symbols​

Instruments​

Record a trace​

Take a screenshot​

Record a video​

Stream video​

Log​

Companion log​

Open a url​

Send a push notification​

Simulate a memory warning​

Clear the keychain​

Set a simulators location​

Read and write preferences​

Add media​

Clear the photo library​

Approve and revoke permissions​

Add contacts​

Interactive shell​

Crash logs​

List crash logs​

Fetch a crash log​

Delete crash logs​

Companion Commands​

Starting a gRPC Server​

Starting a notifier​