Runner CLI¶

skeg-runner executes plans, streams live sessions, serves MCP tools and connects machines. skeg-runner --help prints every flag.

Modes¶

Mode	Purpose
`run` (default)	Execute one plan (`--plan`) or every enabled plan with a tag (`--tag`).
`diagnostics`	Run all plans, collect failures, and write Markdown issue files.
`bridge`	Stream screenshots and the accessibility tree to the inspector.
`daemon`	Register this machine as a runner. Pairs through the browser on first start.
`mcp`	Serve Skeg's tools to an AI agent over MCP stdio. Credential: `SKEG_TOKEN`.
`doctor`	Check server, token, project and targets. Says what to fix.

Credentials¶

Mode	Credential
`daemon`	None up front. It pairs by device code and caches the token in `~/.config/skeg/daemon.token`.
`mcp`, `doctor`	A project token in `SKEG_TOKEN`.
`run`, `diagnostics`, `bridge`	An account session token in `SKEG_RUNNER_TOKEN` (see CI), or `--email`/`--password`.

Run a suite from CI¶

See Run Skeg in CI for a full pipeline.

# SKEG_RUNNER_TOKEN holds an account session token.
skeg-runner --mode run \
  --project <projectId> --tag smoke \
  --platform ANDROID --app-id com.example.app

Flag	Meaning
`--plan` / `--tag`	Exactly one of them.
`--platform`	`IOS`, `ANDROID` or `MACOS`. Required.
`--app-id`	Package or bundle id. Required for a real run.
`--app-path`	Build to install before launch.
`--env`	Environment id. Blank uses the plan's default environment.
`--device`	Device label or serial (for example `emulator-5554`).
`--host`	Android adb host. Default `localhost`.
`--origin`	Provenance for tag runs: `human`, `agent`, `mcp` or `ci` (default).
`--server`	Server URL. Wins over the URL baked into an installed runner.

Exit codes¶

Code	Meaning
`0`	Success.
`1`	A step failed, the run ended as an infrastructure error, `doctor` found a failing check, or `skeg-runner` was called with no arguments (it prints usage).
`2`	Bad arguments the parser rejects, or an unknown mode.
`3`	The runner failed: the server was unreachable, or a check after parsing refused the run. That includes an invalid tag suite (mixed platforms, a platform other than `--platform`, mixed default environments without `--env`) and `--run-id` or `--requires` combined with `--tag`. The `runner failed:` line says which.