# RunnerKit command reference

Use this reference only when the direct `build` or `run` fast path in `SKILL.md` is insufficient. Keep `--json` for agent use and execute through `/usr/local/bin/runnerkit` at the host boundary when the harness is sandboxed.

## Select and inspect

```sh
/usr/local/bin/runnerkit configurations --json
/usr/local/bin/runnerkit config show "Configuration Name" --json
/usr/local/bin/runnerkit status --json
/usr/local/bin/runnerkit operations --limit 10 --json
/usr/local/bin/runnerkit operation show OPERATION-UUID --json
```

An omitted configuration reference means the selected RunnerKit configuration. Exact names and UUIDs are deterministic. Use ranked suggestions from a failed response before issuing broader discovery calls.

## Provision one persistent simulator

Simulator provisioning is a separate, non-paid mutation. It still requires RunnerKit's **Allow agent and command-line control** setting and explicit user authorization. It does not change a saved configuration's destination.

List the selected configuration's Xcode device set, or choose the context explicitly:

```sh
/usr/local/bin/runnerkit simulator list --json
/usr/local/bin/runnerkit simulator list --configuration "Configuration Name" --json
/usr/local/bin/runnerkit simulator list --xcode "/Applications/Xcode-beta.app" --json
```

Create from a simulator configuration's runtime and device type, or provide both explicitly:

```sh
/usr/local/bin/runnerkit simulator create --configuration "Configuration Name" --name "Agent Fresh" --idempotency-key IDEMPOTENCY-UUID --json
/usr/local/bin/runnerkit simulator create --xcode "/Applications/Xcode-beta.app" --runtime "RUNTIME-ID" --device-type "DEVICE-TYPE-ID" --name "Agent Fresh" --idempotency-key IDEMPOTENCY-UUID --json
```

Clone only by an exact source UDID, or let a simulator configuration supply its exact destination UDID:

```sh
/usr/local/bin/runnerkit simulator clone --source SOURCE-UDID --name "Agent Clone" --idempotency-key IDEMPOTENCY-UUID --json
/usr/local/bin/runnerkit simulator clone --configuration "Configuration Name" --name "Agent Clone" --idempotency-key IDEMPOTENCY-UUID --json
```

Generate one UUID for each intended create or clone and reuse that UUID only when retrying the identical request. The running app binds the key before preflight, coalesces identical in-flight calls, rejects conflicting inputs, and can replay recent completed or outcome-unknown results. Preflight failures and failures that prove `simctl` never launched release the key. If the CLI returns `simulator_outcome_unknown`, RunnerKit may have applied the mutation and the CLI deliberately did not resend it. If RunnerKit may have restarted, delivery was ambiguous, or the result says `catalogRefreshed: false`, run `simulator list` with the same context and reconcile the returned UDID/name before considering another mutation.

The result includes the new simulator UDID, runtime, device type, selected Xcode, `isPersistent: true`, and whether it was an idempotent replay. It provisions exactly one device and never retargets the configuration. The CLI has no simulator delete or erase command; persistent cleanup remains a confirmed GUI action in RunnerKit's **Manage Simulators** interface.

## Wait, stop, and recover

```sh
/usr/local/bin/runnerkit operation wait OPERATION-UUID --until built --timeout 600 --json
/usr/local/bin/runnerkit operation wait OPERATION-UUID --until running --timeout 600 --json
/usr/local/bin/runnerkit operation wait OPERATION-UUID --until exited --timeout 600 --json
/usr/local/bin/runnerkit operation stop OPERATION-UUID --timeout 60 --json
```

Stopping changes external process state. Do it only when requested or required by an authorized workflow. A CLI wait timeout does not prove the underlying operation stopped.

## Diagnose with bounded output

```sh
/usr/local/bin/runnerkit diagnose OPERATION-UUID --json
/usr/local/bin/runnerkit logs --operation OPERATION-UUID --summary --json
/usr/local/bin/runnerkit logs --operation OPERATION-UUID --errors --json
/usr/local/bin/runnerkit logs --operation OPERATION-UUID --stage build --errors --json
```

Start with diagnosis and summaries. Read full retained logs only when the concise evidence cannot explain the failure. `logs --follow` applies only to the current operation and cannot be combined with retained-log filters.

## Discover before creating

```sh
/usr/local/bin/runnerkit discover --project "/absolute/path/Project.xcodeproj" --json
/usr/local/bin/runnerkit discover --project "/absolute/path/Workspace.xcworkspace" --scheme "Scheme" --json
```

Discovery is read-only. Use it when no saved configuration matches or the user explicitly asks to inspect available Xcodes, schemes, build configurations, or destinations.

## Configuration changes

Creating, activating, and deleting saved configurations are separate mutations. Perform only the one requested.

```sh
/usr/local/bin/runnerkit config create --project "/absolute/path/Project.xcodeproj" --scheme "Scheme" --destination "Destination Name" --name "Configuration Name" --json
/usr/local/bin/runnerkit config activate "Configuration Name" --json
/usr/local/bin/runnerkit config delete "Configuration Name" --yes --json
```

Use `--allow-provisioning-updates` only when the user explicitly authorizes provisioning or device-registration changes. Configuration deletion never deletes the underlying project, but it still requires the user's intent and `--yes`.

## Health check

```sh
/usr/local/bin/runnerkit version --json
/usr/local/bin/runnerkit doctor --json
```

Do not use these as ritual preflight. `doctor` is for connection, protocol, launcher, Xcode, project, or destination failures that remain after the one permitted host-boundary retry.
