# 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 ```console title="~/app" karagoz devices ``` Takes no options. ## Before you start - On Android: a running emulator (`emulator -avd `), 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 `; 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 ```console title="~/app" $ karagoz devices {"devices":[{"id":"emulator-5554","platform":"android","kind":"emulator","state":"device","name":"Medium_Phone_API_36.1"}]} ``` ### An iOS simulator next to the emulator ```console title="~/app" $ 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"}]} ``` ## Output ```json { "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`](https://karagozmcp.com/docs/commands/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-`, 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-`. 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`](https://karagozmcp.com/docs/error-codes/#invalid-args), [`ADB_NOT_FOUND`](https://karagozmcp.com/docs/error-codes/#adb-not-found), [`ADB_TIMEOUT`](https://karagozmcp.com/docs/error-codes/#adb-timeout) and [`ADB_FAILED`](https://karagozmcp.com/docs/error-codes/#adb-failed). The simctl and devicectl codes come inside `errors` only: [`SIMCTL_NOT_FOUND`](https://karagozmcp.com/docs/error-codes/#simctl-not-found), [`SIMCTL_TIMEOUT`](https://karagozmcp.com/docs/error-codes/#simctl-timeout), [`SIMCTL_FAILED`](https://karagozmcp.com/docs/error-codes/#simctl-failed), [`DEVICECTL_NOT_FOUND`](https://karagozmcp.com/docs/error-codes/#devicectl-not-found), [`DEVICECTL_TIMEOUT`](https://karagozmcp.com/docs/error-codes/#devicectl-timeout) and [`DEVICECTL_FAILED`](https://karagozmcp.com/docs/error-codes/#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 equivalent `devices {}` [MCP tools](https://karagozmcp.com/docs/mcp/#tools) No arguments. ## Related commands - [karagoz install-runner](https://karagozmcp.com/docs/commands/install-runner/): Install Karagöz's runner on an iPhone; the runner field shows its state.