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 (macOS today; Linux coming soon)

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

A Linux client is coming soon. With remote compilation, the Swift code is compiled on the remote host instead of on your machine, so a local Xcode install (and a Mac) will no longer be required.

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 (required for automation)

idb-repl accepts a global --reason "<why>" explaining why you are running it, placed before the subcommand. It is not necessary for humans, but is required for agents. All examples in this documentation include it.