Skip to main content

Commands

iOS Target Manipulation#

Specifying which iOS Target to run against#

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

# Run a describe command against a companion running on the loopback interface# on TCP Port 10882IDB_COMPANION=localhost:10882 idb describe# This can also be a path to a domain socket that the companion is running onIDB_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:

idb connect COMPANION_HOST COMPANION_PORT

Alternatively, pass a UDID instead of an address to transparently start a companion for the provided UDID in the background:

idb connect TARGET_UDID

Manual companion creation can be entirely bypassed by providing a UDID to command invocations. This will transparently start a companion in the background if one is not yet created for the provided UDID. Further invocations for this UDID will use the same companion from the first invocation.

idb describe --udid TARGET_UDID

Disconnect a target#

idb disconnect COMPANION_HOST COMPANION_PORTidb 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.

ArgumentDescriptionDefault
--udid UDIDUDID of the targetIf only one target is connected it'll use that one
--log {DEBUG,INFO,WARNING,ERROR,CRITICAL}Set the log levelCRITICAL
--jsonJSON structured output where applicableFalse

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.

SwitchDescriptionSimulatorsDevices
--bundle-idApply file operations to the "Application Container" of the provided Bundle ID. This is otherwise known as the "Application Sandbox"โœ…โœ… (Only for Applications signed with a Developer Profile)
--mediaThe container for Photos/Videosโœ…โœ…
--crashesThe container for Crash/Diagnostic reports. This can be used to view and pull crash logs from a deviceโŒโœ…

Not all commands will make sense for each container. For example, crash containers are read only. However, file operations provide a consisent abstraction on top of views of heirarchical data.

Copying files into a container#

idb file push --bundle-id com.foo.bar src1.jpg src2.jpg dest_1

Copies one or more files from the host to the relative destination path within the container.

Copying files out of a container#

idb file pull --bundle-id com.foo.bar src.txt dest.txt

Copies a single file from the container to the host.

Moving files within the container#

idb file mv --bundle-id com.foo.bar src1.jpg src2.jpg dest_1

This will move two image files from the root of the container, to a destination subdirectory within the container.

Make a new directory#

idb file mkdir --bundle-id com.foo.bar newdir

Creates a new folder within the apps data container.

Remove a path on a target#

idb file rm PATH_A PATH_B --bundle-id BUNDLE_ID

Removes the specified paths within an apps data container.

If a folder is specified to be deleted, all of its contents will be removed recursively.

List a path on a target#

idb file ls --bundle-id com.foo.bar directory1 directory2

Returns a list of all the files present within one or more directories.

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_NAMEidb 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:

ArgumentDescriptionDefault
--udid UDIDSpecify the target device / simulator
--port PORTThe TCP port to start the gRPC Server on10882
--log-file-path PATHPath to write companion logs toWill log to stderr
--device-set-path PATHiOS 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.