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.

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	If only one target is connected it'll use that one
--log {DEBUG,INFO,WARNING,ERROR,CRITICAL}	Set the log level	CRITICAL
--json	JSON structured output where applicable	False

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.

Interact

For simulators we provide a handful of commands for emulating HID events.

Tap

idb ui tap X Y

Taps a location on the screen specified in the points coordinate system. The tap duration can be set with --duration

Swipe

idb ui swipe X_START Y_START X_END Y_END

Swipes from the specified start point to the end. By default this will be done by a touch down at the start point, followed by moving 10 points at a time until the end point is reached. The size of each step can be specified with --delta.

Press a button

idb ui button {APPLE_PAY,HOME,LOCK,SIDE_BUTTON,SIRI}

Simulates a press of the specified button. The press duration can be set with --duration.

Inputting text

idb ui text "some text"

Types the specified text into the target.

idb ui key 4

Simulates the press of a key specified by its keycode. The key presses duration can be set with --duration.

idb ui key-sequence 4 5 6

Inputs multiple key events sequentially.

Accessibility info

Describe the whole screen

idb ui describe-all

Returns a JSON formatted list of all the elements currently on screen, including their bounds and accessibility information.

Describe a point

idb ui describe-point X Y

Returns JSON formatted information about a specific point on the screen, if an element exists there.

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.

Instruments

idb instruments TEMPLATE

Starts instruments running connected to the target

Record a video

idb record video OUTPUT_MP4

Starts recording the targets screen, outputting the content to the specified path. The recording can be stopped by pressing ^C.

Log

idb log

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

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.

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.

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.

Approve

idb approve com.apple.Maps photos camera

For simulators idb can programmatically approve permission for an app. Currently idb can approve:

• photos - Permission to view the camera roll
• camera - Permission to access the camera
• contacts - Permission to access the targets contacts

Add contacts

idb contacts update db.sqlite

For simulators idb can overwrite the simulators contacts db.

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
--port PORT	The TCP port to start the gRPC Server on	10882
--log-file-path PATH	Path to write companion logs to	Will log to stderr
--device-set-path PATH	iOS Simulator custom device set path	~/Library/Developer/CoreSimulator/Devices

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.