karagoz install-runner

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

iOS device Done

Usage

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	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

Picks the team: --team, else the teams Xcode saved for the Apple accounts in Xcode > Settings > Accounts.
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.
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`	No Xcode, no Apple account or team in Xcode, a failed build with xcodebuild's error lines and the log path.
`INVALID_ARGS`	A malformed `--team`, or several teams and none chosen.
`INSTALL_FAILED`	The device refused the app; the message is devicectl's.
`DEVICE_NOT_READY`	Not paired, Developer Mode off, locked.
`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 equivalentinstall_runner {}MCP tools

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

karagoz ui-tree: Uses the runner on an iPhone, as tap, swipe, text and key do.