# karagoz install-runner

Builds Karagöz's runner with your Apple team and installs it on a paired iPhone.

- iOS device Done

## Usage

```console title="~/app"
karagoz install-runner [--device <id>] [--team <ID>]
```

macOS only.

The runner is the small XCUITest bundle that `ui-tree`, `tap`, `swipe`, `text` and `key` use on an iPhone. `install-runner` is the one command that puts something of Karagöz’s on a device.

## Before you start

- An Apple ID signed in to Xcode > Settings > Accounts whose team Xcode has saved, or `--team`. Xcode saves the team once a project’s Signing & Capabilities tab has been opened.
- A free Apple ID (Personal Team) also signs the runner, untested. The phone then asks once to trust the developer (Settings > General > VPN & Device Management, needs internet).

## Options

| Option          | Default                                                               | Meaning                                                                                      |
| --------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `--device <id>` | see [Device selection](https://karagozmcp.com/docs/device-selection/) | An iPhone’s UDID or model. A simulator or an Android device is refused with `NOT_SUPPORTED`. |
| `--team <ID>`   | the only team in Xcode, else the only paid one                        | The 10-character Apple team ID to sign with.                                                 |

## Output

- `device` string: The iPhone's UDID.
- `bundleId` string: The runner app on the phone: `com.karagozmcp.runner.<team, lowercased>.xctrunner`. The team keeps the id unique, which a free account needs.
- `team` string: The team it was signed with.

## What it does

1. Picks the team: `--team`, else the teams Xcode saved for the Apple accounts in Xcode > Settings > Accounts.
2. Builds with `xcodebuild build-for-testing` and automatic signing (`-allowProvisioningUpdates`, `-allowProvisioningDeviceRegistration`) into `~/Library/Caches/karagoz/runner/`. Xcode creates a development certificate in your keychain when there is none, registers the iPhone on your developer account and signs with a team profile; with a paid team it used the team’s wildcard profile. These stay on your Mac and account.
3. Installs the app with `devicectl device install app`.

Run it again:

- after updating Karagöz or Xcode
- for another iPhone
- with a free account, when its 7-day profile runs out
- after deleting the `runner/` folder

After deleting the folder, while a runner started before is still up (up to 10 minutes), calls to that iPhone fail with `DEVICE_NOT_READY`.

## Errors

| Code                                                                            | When                                                                                                        |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| [`HELPER_FAILED`](https://karagozmcp.com/docs/error-codes/#helper-failed)       | No Xcode, no Apple account or team in Xcode, a failed build with xcodebuild's error lines and the log path. |
| [`INVALID_ARGS`](https://karagozmcp.com/docs/error-codes/#invalid-args)         | A malformed `--team`, or several teams and none chosen.                                                     |
| [`INSTALL_FAILED`](https://karagozmcp.com/docs/error-codes/#install-failed)     | The device refused the app; the message is devicectl's.                                                     |
| [`DEVICE_NOT_READY`](https://karagozmcp.com/docs/error-codes/#device-not-ready) | Not paired, Developer Mode off, locked.                                                                     |
| [`NOT_SUPPORTED`](https://karagozmcp.com/docs/error-codes/#not-supported)       | A simulator or an Android device: `device <id> is not an iPhone; karagoz's runner runs only on iPhones.`    |

`install-runner` can also get the devicectl errors and the device selection errors.

## Notes

- The first run takes about 17 s: build, certificate and profile, install. With the build cached, about 3 s.
- The build needs the network the first time: Xcode talks to Apple’s developer service.

## MCP equivalent

MCP equivalent `install_runner {}` [MCP tools](https://karagozmcp.com/docs/mcp/#tools)

Arguments: `team`, `device`. The names are the CLI's option and positional names.

## Related commands

- [karagoz ui-tree](https://karagozmcp.com/docs/commands/ui-tree/#on-an-iphone): Uses the runner on an iPhone, as tap, swipe, text and key do.