idb (iOS Development Bridge)

FBDeviceControl is a framework designed for controlling iOS Devices. It is a sister-framework to FBSimulatorControl (which is used for iOS Simulators).

While you can use FBDeviceControl as a standalone framework, it is recommended to use idb, which utilizes FBDeviceControl under the hood and provides more sensible default configurations for many common use cases.

The idb ecosystem is built upon several core frameworks that can be used independently of the idb CLI.

• FBControlCore: Defines common interfaces and provides shared functionality for both Device and Simulator frameworks.
• FBSimulatorControl: Implements functionality specific to iOS Simulators.
• FBDeviceControl: Implements functionality specific to physical iOS Devices.

These frameworks use an abstraction layer where FBiOSTarget (a protocol) represents either a simulator or a device, allowing higher-level tools to treat them uniformly.

The idb system consists of two primary components that must both be present to execute commands:

1. idb cli: A Python 3-based command-line interface that serves as a thin wrapper for the idb_companion. It communicates with the companion via gRPC (using either TCP or Unix Domain Sockets). Because it is Python-based, the CLI does not need to run on the same Mac that is physically attached to the iOS device or simulator.
2. idb_companion: A gRPC server that must run on macOS. It interfaces with native APIs to automate Simulators and Devices by linking the FBSimulatorControl and FBDeviceControl frameworks. Each idb_companion instance acts as a server for a single iOS target (one specific device or simulator).

The idb-repl workflow consists of three main components that orchestrate code execution on a simulator:

1. idb-repl (the driver): The CLI tool you interact with. It compiles your Swift code and orchestrates the session. It communicates with the companion via gRPC but does not talk to the target process directly.
2. idb_companion (the server): A macOS process that manages simulators and exposes a gRPC API. It is responsible for injecting and running your code inside the target process.
3. The target process: The actual environment where your code executes, which can be an app, the simulator itself, or a test bundle.

Data Flow: you ──▶ idb-repl (driver) ──(gRPC)──▶ idb_companion (server) ──▶ target process on the simulator (app / simulator / test bundle)

The idb_companion acts as a gRPC server that exposes the functionality of the FBSimulatorControl and FBDeviceControl frameworks.

Key components:

• main: The entrypoint for the companion. It handles gRPC server startup flags and exposes destructive "CRUD" commands for managing Simulators and Devices. Note that destructive commands are intentionally excluded from the gRPC interface and must be run on the host.
• FBIDBServiceHandler: A C++ class implementing the gRPC interface. It forwards requests to a thread pool and manages the conversion of gRPC calls to underlying framework calls (often involving FBFuture).
• FBIDBCommandExecutor: An Objective-C facade that provides a simplified interface over the underlying frameworks, shielding the C++ service handler from complex framework implementation details.

FBDeviceControl is a standalone macOS Framework that implements iOS device functionality for idb. It is built upon Apple's private MobileDevice.framework (typically located at /System/Library/PrivateFrameworks/MobileDevice.framework/MobileDevice).

Key integration details:

• API Style: Most MobileDevice.framework APIs are CoreFoundation-style (C symbols with CF objects). FBDeviceControl wraps these into Objective-C classes like FBAMDevice.
• Xcode Dependency: Some device operations require Xcode to be installed and selected via xcode-select. FBDeviceControl defers loading Xcode-specific functionality to avoid failures when Xcode is not required (e.g., basic device listing works without Xcode).
• Canonical Source: FBDeviceControl uses these APIs as the canonical way to interact with iOS devices on macOS, similar to how Finder, iTunes, and Xcode operate.

While the "Default Device Set" is located at ~/Library/Developer/CoreSimulator/Devices and used by Xcode.app, you can place custom device sets at any location on disk. This is useful for:

• Isolating filesystems of different iOS Simulators.
• Preventing data races when multiple independent processes manage iOS Simulators on the same host.

Interactive mode is experimental and incomplete. For reliable, scriptable use, prefer one-shot mode by passing Swift code as a trailing argument.

In an interactive session (running a subcommand without a trailing code argument), lines that do not start with / are treated as Swift code. To execute the collected code, use the /run command. The collected code must end in a return statement to surface a value.

Interactive Commands: