karagoz devices

Lists what adb devices lists and, on macOS, the iOS simulators that are running and the iPhones connected to the Mac.

Android emulator Done
Android device Done
iOS simulator Done
iOS device Done

Usage

karagoz devices

Takes no options.

Before you start

On Android: a running emulator (emulator -avd <name>), or a phone with USB debugging on, in state device.
On an iOS simulator: Xcode, opened once, and a booted simulator (on Xcode 27, xcrun simctl boot <name>; on older ones, open -a Simulator). The Command Line Tools alone have no simctl.
On an iPhone: Xcode 15 or newer, and the iPhone connected to the Mac. The Command Line Tools alone have no devicectl.

Examples

List the devices

$ karagoz devices
{"devices":[{"id":"emulator-5554","platform":"android","kind":"emulator","state":"device","name":"Medium_Phone_API_36.1"}]}exit 0

An iOS simulator next to the emulator

$ karagoz devices
{"devices":[{"id":"emulator-5554","platform":"android","kind":"emulator","state":"device","name":"Medium_Phone_API_36.1"},{"id":"4E70BFCA-5FC6-49B5-92EC-48E265B2D50F","platform":"ios","kind":"simulator","state":"Booted","name":"iPhone 17 Pro"}]}exit 0

Output

{
  "devices": [
    {
      "id": "emulator-5554",
      "platform": "android",
      "kind": "emulator",
      "state": "device",
      "name": "Medium_Phone_API_36.1"
    }
  ]
}

No devices is not an error: {"devices":[]}, exit 0. Android devices come first in adb’s order, then simulators in simctl’s order, then iPhones in devicectl’s order.

devices array: What adb devices lists and, on macOS, the iOS simulators that are running and the iPhones connected to the Mac.
devices[].id string: The adb serial, or the simulator's or iPhone's UDID. Pass it to --device.
devices[].platform string: One of android, ios.
devices[].kind string: One of emulator, physical, simulator: simulator for iOS simulators, physical for iPhones. See below.
devices[].state string: adb's state, unchanged: device, offline, unauthorized, ... Only device can be used. See below.
devices[].name string or null: Emulator: the AVD name. Android phone: the model (ro.product.model). Simulator: the simulator's name. iPhone: the model (iPhone 14 Pro Max). See below.
devices[].runner string or null: iPhones only: Karagöz's runner (install-runner) on the phone. running when it answers, installed or not installed from the phone's app list, null for an iPhone that is not paired or whose app list could not be read.
errors array: Only when adb, simctl or devicectl is missing, fails or hangs: one entry per failed listing, two ios entries when simctl and devicectl both fail. The other listings are still printed and the exit is 0.
errors[].platform string: One {"platform","code","message"} per failed listing.
errors[].code string: One {"platform","code","message"} per failed listing.
errors[].message string: One {"platform","code","message"} per failed listing.

kind is emulator when the id is emulator-<port>, or when the device reports ro.boot.qemu or ro.kernel.qemu as 1, or ro.hardware as ranchu or goldfish (an emulator attached with adb connect). Genymotion, and other ids not in state device, read as physical.

For simulators, state is simctl’s state: Booted, Booting, Shutting Down; only Booted is usable. For iPhones, it is devicectl’s pairing state: paired, unpaired (unlock the phone and tap Trust when it asks), pairingInProgress.

name is null for an unpaired iPhone, and for a paired one devicectl is not connected to: right after pairing, or when the connection went idle. Pick it by UDID then. name is also null when the device does not answer, or when it is not in state device and its id is not emulator-<port>.

When every listing tried fails, Android’s error is printed as the usual envelope and the exit is 1.

On Linux and Windows, simulators and iPhones are not looked for.

Errors

devices can return INVALID_ARGS, ADB_NOT_FOUND, ADB_TIMEOUT and ADB_FAILED.

The simctl and devicectl codes come inside errors only: SIMCTL_NOT_FOUND, SIMCTL_TIMEOUT, SIMCTL_FAILED, DEVICECTL_NOT_FOUND, DEVICECTL_TIMEOUT and DEVICECTL_FAILED.

Notes

Not listed:
- shut-down simulators
- watchOS, tvOS and visionOS simulators
- iPhones on iOS 16 and older
- phones paired before but not connected now
- nearby devices that could be paired
An iPad is listed the way an iPhone is.
The first call after login can take several seconds while macOS starts the simulator service (30 s limit).
A phone is missing from the list when adb cannot see it:
- on Windows without the phone maker’s USB driver
- on a Mac laptop where “Allow accessory to connect” was refused
- in fastboot mode
A device listed as (no serial number), or two devices that share one serial, cannot be targeted: adb’s -s cannot tell them apart.
Karagöz does not pair or connect over Wi-Fi. Use adb pair and adb connect; a paired Android 11+ phone reconnects by itself.
If an emulator’s name comes back null, check that HOME points to your home directory; the emulator console reads a token from there.

MCP equivalent

MCP equivalentdevices {}MCP tools

No arguments.

karagoz install-runner: Install Karagöz's runner on an iPhone; the runner field shows its state.