Requirements

idb-repl runs Swift code inside a process on an iOS Simulator via an idb companion. Here's what your setup needs.

The client

idb-repl runs on macOS. It compiles the Swift you enter locally, so you need Xcode installed locally to provide the Swift toolchain — this is true even when you are working with a remote simulator.

idb-repl targets iOS Simulators. REPL injection and UI automation are simulator features — it is not a way to inject code for physical devices.

idb-repl and idb_companion on your PATH

For local use, idb-repl and idb_companion must be installed and on your PATH. You don't need to start the companion yourself — idb-repl will launch it for you.

Check the idb-repl build you have with:

idb-repl --version   # prints the build date and time

A target simulator

Local (default)

Boot an iOS simulator and pass its UDID with --udid <udid> — that's all you need. idb-repl starts a companion for that simulator on its own.

idb list-targets   # find the UDID of a booted simulator

You may omit --udid only when exactly one simulator is booted; if several are booted (or none), idb-repl errors and asks you to specify one.

Remote

To drive a remote simulator, set up idb_companion on the remote host yourself and connect to it explicitly with --companion <host:port>. Unlike local use, this is not set up automatically — there is currently no discovery for remote companions. See Examples → Remote companion and the CLI reference.

--reason

idb-repl accepts a global --reason "<why>" explaining why you are running it, placed before the subcommand. Automation should always pass it, and all examples in this documentation include it.