# Device selection

How Karagöz picks the one device a command works on, and the errors when none or several match.

Every command except [`devices`](https://karagozmcp.com/docs/commands/devices/) and [`doctor`](https://karagozmcp.com/docs/commands/doctor/) works on one device, picked in this order:

1. `--device <id>`
2. the `KARAGOZ_DEVICE` environment variable
3. the `ANDROID_SERIAL` environment variable
4. the only listed device

A variable is ignored when anything above it is given; an empty one counts as unset. `KARAGOZ_DEVICE` names a device on either platform. There is no config file.

## Matching

The value is matched against every listed id first, exactly: adb serials (`emulator-5554`) and, on macOS, the UDIDs of booted simulators and connected iPhones.

If no id matches, it is matched against every `name` that `devices` prints, exactly and case-sensitively:

- an emulator’s AVD name (`Medium_Phone_API_36.1`)
- a phone’s model (`SM-S908N`)
- a simulator’s name (`iPhone 17 Pro`)
- an iPhone’s model (`iPhone 14 Pro Max`)

A name matched on both platforms, or by an iPhone and a simulator, is ambiguous; neither wins.

## Errors

| Situation                                                                                                                                                                                                                               | Error                                                                                                      |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| A value is given and nothing matches                                                                                                                                                                                                    | [`DEVICE_NOT_FOUND`](https://karagozmcp.com/docs/error-codes/#device-not-found), listing what is connected |
| No value, nothing connected                                                                                                                                                                                                             | [`NO_DEVICE`](https://karagozmcp.com/docs/error-codes/#no-device)                                          |
| No value and two or more devices listed (in any state), or a name that matches two entries: the same AVD listed as `emulator-5554` and `127.0.0.1:5555`, or two phones of the same model                                                | [`DEVICE_AMBIGUOUS`](https://karagozmcp.com/docs/error-codes/#device-ambiguous)                            |
| `install-runner` or `uninstall-runner` picked a simulator or an Android device. This comes before any readiness check.                                                                                                                  | [`NOT_SUPPORTED`](https://karagozmcp.com/docs/error-codes/#not-supported)                                  |
| The picked device is not in state `device` (`offline`, `unauthorized`, …), a simulator not `Booted` (`Booting`, `Shutting Down`), or an iPhone not `paired` (`unpaired`, `pairingInProgress`; the message says what to do on the phone) | [`DEVICE_NOT_READY`](https://karagozmcp.com/docs/error-codes/#device-not-ready)                            |

Karagöz never guesses between devices.

## On macOS

Every command that targets a device lists booted simulators and connected iPhones next to adb’s devices, in parallel.

- A missing `adb`, `simctl` or `devicectl` means that listing has no devices. When nothing is listed and `adb` is missing, the error is [`ADB_NOT_FOUND`](https://karagozmcp.com/docs/error-codes/#adb-not-found).
- Any other failure of one listing stops the command, unless the value is an id another listing returned. A hung simulator service makes a bare call fail with [`SIMCTL_TIMEOUT`](https://karagozmcp.com/docs/error-codes/#simctl-timeout) after 30 s. A hung CoreDevice service makes it fail with [`DEVICECTL_TIMEOUT`](https://karagozmcp.com/docs/error-codes/#devicectl-timeout) after 10 s.

## Wi-Fi and USB

A phone connected over Wi-Fi as well as USB is listed twice, once per serial, and its model matches both: pick it by serial then. Quote a `--device` value that contains spaces, as some mDNS serials do.