--- id: commands title: 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](https://developer.apple.com/documentation/foundation/nsuuid), for Devices it depends on the phone model, but the [iPhone Wiki has an overview of the formats](https://www.theiphonewiki.com/wiki/UDID). 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 `connect`ing 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.](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](test-execution) 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](file-containers). ## 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. `UDID`s 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.