Device Discovery via devicectl#

Overview#

Tuist wraps Apple's devicectl CLI (available via xcrun devicectl) to discover and interact with physical Apple devices. The abstraction lives in TuistAutomation and is consumed by RunCommandService to support tuist run on real hardware.

Key files:

DeviceControlling Protocol#

The DeviceControlling protocol (annotated @Mockable for test injection) exposes three async operations:

• findAvailableDevices() -> [PhysicalDevice] — enumerate all known physical devices
• installApp(at:device:) — sideload a .app bundle onto a device
• launchApp(bundleId:device:) — launch an installed app by bundle ID

Device Discovery — findAvailableDevices()#

findAvailableDevices() runs:

/usr/bin/xcrun devicectl list devices --json-output <tmp_file>.json

The JSON output is written to a temporary directory (via FileSystem.runInTemporaryDirectory) and then decoded into the private DeviceList struct. Any decode failure surfaces as DeviceControllerError.fetchingDevicesFailed 1.

JSON Decoding & Filtering#

The private DeviceList hierarchy mirrors the devicectl JSON schema:

• connectionProperties: holds transportType (.localNetwork | .wired) and tunnelState (.connecting | .connected | .disconnected | .unavailable)
• deviceProperties: name, osVersionNumber
• hardwareProperties: udid, platform (.iOS | .tvOS | .watchOS | .visionOS)

A device is silently dropped (compactMap) if any of udid, platform, or name is missing 2. This guards against partially-populated entries that devicectl may return (e.g., paired-but-never-seen devices).

Transport Type Mapping#

The devicectl transportType field is mapped to PhysicalDevice.TransportType 3:

Note on sameMachine: The ConnectionProperties.TransportType enum in the current code only models localNetwork and wired 4. A device reporting any other raw value (including a hypothetical sameMachine string) will decode transportType as nil, which is legal — the device is still included and simply has no transport type set.

Connection State Mapping#

tunnelState is mapped to PhysicalDevice.ConnectionState 5: only connected maps to .connected; all other states (connecting, disconnected, unavailable, or absent) map to .disconnected.

PhysicalDevice Model#

Defined in PhysicalDevice.swift, it is a Codable, Equatable, Identifiable struct:

• id: String — the device UDID (from hardwareProperties.udid)
• name: String
• platform: Platform — XcodeGraph Platform enum
• osVersion: String?
• transportType: TransportType? — .wifi or .usb
• connectionState: ConnectionState — .connected or .disconnected

Installation & Launch#

Once devices are discovered, RunCommandService 6 calls:

1. deviceController.installApp(at:device:) → xcrun devicectl device install app --device <udid> <path>
2. deviceController.launchApp(bundleId:device:) → xcrun devicectl device process launch --device <udid> <bundleId>

If install stderr contains "ApplicationVerificationFailed", the error is caught and re-thrown as DeviceControllerError.applicationVerificationFailed with a user-friendly message directing the developer to register the device in their Apple Developer account 7.

Integration with RunCommandService#

During tuist run, RunCommandService calls deviceController.findAvailableDevices() (macOS only, guarded with #if os(macOS)) and appends results as DestinationDevice.physical entries alongside simulators and Android devices. If a --device flag is provided, the service matches by name; otherwise it prompts interactively or auto-selects the single ready device.

Error Cases#

Both are .abort errors 8, causing the CLI to exit immediately.