Groundrun CLI cheat sheet
groundrun is the command-line tool for compiling test scenarios, driving a
rig, running a continuous-integration gate, and reporting on the value a
test suite delivers. Every command supports --help at every level:
groundrun --help, groundrun rig --help, groundrun rig run --help, and
so on, each printing the exact flags and defaults available.
Most rig and ci commands need a running coordinator and, for many of
them, a rig you currently hold a lease on. Acquire a rig first
(groundrun rig acquire <rig-name>), then run commands against it; release
it (groundrun rig release) when done. A handful of commands — reading or
writing rig inventory settings such as a power switch —
need no lease at all; those are called out below.
Examples below use placeholder names: bench-1 (and bench-2 for a
second rig) for rig names, and my-app/my-scenario (and variants such as
my-app/network-formation) for scenario names. Replace them with your own.
Angle-bracket values like <path> or <date> mark something you fill in;
everything else is typed as shown.
Compiling scenarios
| Command | Description | Example |
|---|---|---|
groundrun compile <rig.yaml> <scenario.yaml> [<scenario.yaml> ...] --output <dir> |
Compile a rig description and one or more scenario files into a runnable test suite, entirely offline (no coordinator or rig needed). Add --wait-timeout-multiplier <N> to scale every wait step's timeout, for a slower or noisier bench. |
groundrun compile rig.yaml scenarios/my-scenario.yaml --output build/tests |
Connecting to a rig
| Command | Description | Example |
|---|---|---|
groundrun rig login --coordinator <url> |
Save the coordinator's address so every later groundrun rig/ci command can find it without repeating --coordinator. Run once per machine. |
groundrun rig login --coordinator https://coordinator.example.com |
Checking rig status and history
| Command | Description | Example |
|---|---|---|
groundrun rig rigs [--format human|json] |
List the rigs the coordinator knows about, their capabilities, and whether each is currently leased. | groundrun rig rigs --format human |
groundrun rig runs [--scenario NAME] [--rig NAME] [--status STATUS] [--driver agent|ci|user] [--since DURATION] [--recorded NAME[=VALUE]] |
List past runs, most recent first, filtered by scenario, rig, outcome, who started it, or how long ago. | groundrun rig runs --scenario my-app/my-scenario --since 7d |
groundrun rig corpus [--scenario NAME] [--rig NAME] [--group-by rig|scenario|status] [--pattern TEXT] [--predecessor] |
Summarize a larger set of past runs at once: pass/fail rates grouped by rig or scenario, or a run list annotated with which run came before which. | groundrun rig corpus --scenario my-app/my-scenario --group-by status --since 30d |
groundrun rig headroom <scenario> |
Show how close a scenario's wait steps run to their declared time limits, across its run history — useful for spotting a limit that is about to become too tight. | groundrun rig headroom my-app/my-scenario |
groundrun rig contention [--rig NAME] [--since DURATION] |
List times a rig was requested while already leased by someone else. | groundrun rig contention --rig bench-1 --since 7d |
Managing scenarios and rig configuration
| Command | Description | Example |
|---|---|---|
groundrun rig scenarios [--query TEXT] |
List scenarios the coordinator has stored, optionally filtered by text in their content. | groundrun rig scenarios --query network |
groundrun rig scenario push <file> --name <owner/name> [--ttl <seconds>] |
Upload a scenario file to the coordinator under a name, so a later run can reference it by that name instead of re-uploading it. |
groundrun rig scenario push scenarios/my-scenario.yaml --name my-app/my-scenario |
groundrun rig scenario get <owner/name> [--sha256 <hash>] [-o <path>] |
Download a previously uploaded scenario. | groundrun rig scenario get my-app/my-scenario -o my-scenario.yaml |
groundrun rig scenario rm <owner/name> |
Delete a previously uploaded scenario. | groundrun rig scenario rm my-app/my-scenario |
groundrun rig scenario failures |
List scenario files or uploads the coordinator could not load, and why. | groundrun rig scenario failures |
groundrun rig yaml push <rig> <file> |
Replace a rig's own configuration file (board list, connections) on the coordinator. | groundrun rig yaml push bench-1 rig.yaml |
groundrun rig yaml get <rig> <identity> [--sha256 <hash>] [-o <path>] |
Download a rig's stored configuration file. | groundrun rig yaml get bench-1 rig.yaml -o rig.yaml |
groundrun rig yaml rm <rig> <identity> |
Remove a rig's stored configuration file. | groundrun rig yaml rm bench-1 rig.yaml |
Reserving and controlling a rig
| Command | Description | Example |
|---|---|---|
groundrun rig acquire [<rig> ...] [--needs CAPABILITY] [--ttl <seconds>] [--wait] [--wait-timeout <seconds>] [--owner NAME] |
Reserve one or more rigs so nobody else can use them while you work, for up to --ttl seconds unless renewed. Name a rig directly, or ask for one by capability with --needs. Add --wait to queue until a matching rig frees up instead of failing immediately. |
groundrun rig acquire bench-1 --ttl 1800 |
groundrun rig renew [--ttl <seconds>] |
Extend how much longer you hold every rig you currently have reserved. | groundrun rig renew --ttl 1800 |
groundrun rig hold [--ttl <seconds>] [--max-seconds <seconds>] [--watch-pid <pid>] |
Keep renewing your reservation automatically in the background, for up to --max-seconds, while you do work that is not itself a single run. |
groundrun rig hold --max-seconds 3600 |
groundrun rig release [--rig <rig> --lease-id <id>] [--on <rig>] [--all] |
Give up your reservation on a rig so others can use it. Bare release frees everything you hold; --on <rig> frees just one; --rig/--lease-id frees a reservation directly against the coordinator when you no longer have local reservation state to read (for example after a crashed process). |
groundrun rig release |
groundrun rig wait --idle [--rig <rig>] [--timeout <seconds>] [--interval <seconds>] |
Block until a rig you can see becomes free, then return. | groundrun rig wait --idle --rig bench-1 --timeout 1800 |
groundrun rig preflight |
Check whether your reserved rig's hardware answers at all, before deploying anything to it. Never powers anything on. | groundrun rig preflight |
groundrun rig self-test |
Run a rig's built-in hardware self-check (power, boards, phone) and print a per-check report. | groundrun rig self-test |
groundrun rig supervisor-provision |
Install or update this rig's supervisory software (the layer that controls power and hardware resets), on a rig you currently hold. | groundrun rig supervisor-provision |
groundrun rig reset --mode hard|soft|none [--keep-phone-bonds] |
Reset your reserved rig. hard power-cycles it; soft resets without cutting power; none does nothing. A hard reset also clears the phone's paired-device list unless --keep-phone-bonds is given. |
groundrun rig reset --mode hard |
groundrun rig power-switch show|set|clear <rig> [--ip <ip>] [--model shelly|kasa] [--outlet <n>] |
Read, set, or clear which network-controlled power outlet a rig uses. Does not require a reservation and does not itself turn power on or off. | groundrun rig power-switch set bench-1 --ip 192.0.2.10 --model shelly --outlet 0 |
groundrun rig phone-shared-with show|set|clear <rig> [<other-rig>] |
Read, set, or clear which other rig shares this rig's phone. Setting it links both rigs together so only one can be reserved with the phone at a time. Does not require a reservation. | groundrun rig phone-shared-with set bench-1 bench-2 |
Running scenarios and reading results
| Command | Description | Example |
|---|---|---|
groundrun rig run --scenario <name>=<path> [--scenario ...] [--all] [--artifact <slot>=<path>] [--reset hard|soft|none] [--driver agent|ci|user] [--branch <name>] [--pr <number>] [--follow] [--no-resume] [--keep-phone-bonds] [--wait-timeout-multiplier <n>] |
Run one or more scenarios on your reserved rig, uploading any firmware or file artifacts they need. --follow streams progress until the run finishes instead of returning immediately. |
groundrun rig run --scenario my-app/my-scenario=scenarios/my-scenario.yaml --artifact firmware=build/firmware.bin --reset hard --driver user --follow |
groundrun rig cancel <run-id> [--force] |
Stop a run in progress. | groundrun rig cancel run-abc123 |
groundrun rig status <run-id> |
Show a run's current status and the tail of its log. | groundrun rig status run-abc123 |
groundrun rig results <run-id> |
Show a summary of a finished run's results. | groundrun rig results run-abc123 |
groundrun rig record <run-id> [--format json|md] [--out <path>] |
Export a run's full record — outcome, per-scenario results, and pass-criteria detail — for attaching to a pull request or report. | groundrun rig record run-abc123 --format md --out run-report.md |
groundrun rig baseline record <run-id> --name <name> --file <path> [--target <name>] |
Save a run's measurements as a named baseline, to compare later runs against. | groundrun rig baseline record run-abc123 --name release-baseline --file baseline.json |
groundrun rig report [<run-id>] [--outcome <outcome>] [--exit-code <n>] [--summary <path>] [--annotate] [--note <text>] |
Render a run's outcome as a readable report and exit with a matching status code, for use as a CI step's own job summary. | groundrun rig report run-abc123 --annotate |
groundrun rig fetch <run-id> [<name>] [--all] [--out-dir <dir>] [--out <path>] |
Download one artifact a run produced (by name), or every artifact it produced with --all. |
groundrun rig fetch run-abc123 --all --out-dir ./artifacts |
groundrun rig diff <run-a> <run-b> <name> [--out-dir <dir>] |
Compare the same-named artifact from two runs and print the differences. | groundrun rig diff run-abc123 run-def456 test-output.log |
Working with a rig's hardware directly
| Command | Description | Example |
|---|---|---|
groundrun rig runner-exec <command> [--timeout <seconds>] |
Run one shell command on your reserved rig's main controller and print its output and exit code. | groundrun rig runner-exec "uname -a" |
groundrun rig lan-exec <command> [--timeout <seconds>] |
Run one shell command on a rig's secondary network-attached diagnostic host, when the rig has one. | groundrun rig lan-exec "ping -c1 192.0.2.30" |
groundrun rig phone-shell <command> |
Run one shell command on your reserved rig's phone and print its output. | groundrun rig phone-shell "getprop ro.build.version.release" |
groundrun rig phone-record start |
Start recording your reserved rig's phone screen. | groundrun rig phone-record start |
groundrun rig phone-record stop --out <path> |
Stop the phone screen recording, download it, and save it locally. | groundrun rig phone-record stop --out recording.mp4 |
groundrun rig phone-screenshot [--out <path>] |
Capture and download a single screenshot of your reserved rig's phone. | groundrun rig phone-screenshot --out screenshot.png |
groundrun rig phone-bonds [--clear] |
List the Bluetooth devices your reserved rig's phone is currently paired with. With --clear, forget all of them. |
groundrun rig phone-bonds --clear |
groundrun rig phone-pair <address> |
Ask your reserved rig's phone to attempt pairing with a Bluetooth address, useful for deliberately raising a pairing prompt to test against. | groundrun rig phone-pair AA:BB:CC:DD:EE:FF |
groundrun rig phone-install <apk> [--replace] |
Install an app on your reserved rig's phone. Add --replace to uninstall a conflicting existing install first and retry. |
groundrun rig phone-install my-app.apk --replace |
groundrun rig push-file <local> <remote> [--role runner|supervisor] |
Copy one local file onto your reserved rig's main controller (or, with --role supervisor, its supervisory controller), outside of a run. |
groundrun rig push-file ./tools/my-script.sh /tmp/groundrun-push/my-script.sh |
groundrun rig push-directory <local> <remote> --mode mirror|merge |
Copy a local directory tree onto your reserved rig's main controller, outside of a run. mirror removes anything at the destination that isn't in the source; merge does not. |
groundrun rig push-directory ./tools /tmp/groundrun-push/tools --mode merge |
groundrun rig load-diagnostics [--package <name>] [--timeout <seconds>] |
Install diagnostic tools (packet capture, network utilities) on your reserved rig's main controller, reporting which were already present, newly installed, or failed to install. | groundrun rig load-diagnostics --package iw |
groundrun rig phone-packages [<filter>] |
List apps installed (and apps uninstalled but with data left behind) on your reserved rig's phone, optionally filtered by a substring of the package name. | groundrun rig phone-packages my-app |
groundrun rig cleanup-apk <apk> |
Install or update Groundrun's own housekeeping app on your reserved rig's phone, and make sure it has the permissions it needs. | groundrun rig cleanup-apk cleanup.apk |
groundrun rig board-exec <role> [<command>] [--read-seconds <n>] [--until <pattern>] [--baud <n>] [--flow-control none|hardware] |
Send an optional command to one board on your reserved rig over its serial connection and read back what it prints. Omit the command for a read-only capture. | groundrun rig board-exec leaf "status" --read-seconds 5 |
Continuous integration
| Command | Description | Example |
|---|---|---|
groundrun ci run --rig <rig> [--rig <rig> ...] [--scenario <name>=<path> ...] [--step <rig>:<name>=<path> ...] [--artifact <slot>=<path> ...] [--artifact-dir <dir>] [--ttl <seconds>] [--wait-timeout <seconds>] |
Run a rig gate end to end from a CI job in one command: reserve the rig(s), check they answer, upload scenarios and artifacts, run the scenario(s), download every result artifact, and report the outcome — releasing the reservation on the way out whatever happens. Give more than one --rig when a scenario needs two rigs reserved together; use --step instead of --scenario when two rigs each need their own separate scenario run, in sequence, under one reservation. |
groundrun ci run --rig bench-1 --scenario my-app/my-scenario=scenarios/my-scenario.yaml --artifact firmware=build/firmware.bin --artifact-dir ./rig-artifacts |
groundrun ci teardown --rig <rig> [--rig <rig> ...] |
Release a rig reservation left behind after a CI job was cancelled or killed before ci run could clean up after itself. Place it in a step that always runs (even after cancellation); it is a safe no-op if there is nothing to release. |
groundrun ci teardown --rig bench-1 |
Value and ROI reporting
| Command | Description | Example |
|---|---|---|
groundrun value baseline create --output <path> --customer-name <name> --capture-date <date> --release-cadence <n> --qa-hours <hours> --qa-days <days> --confidence-method <text> [--last-incident <date>] [--incident-cost <amount>] [--critical-flow <name> ...] |
Create a baseline document describing a customer's current manual-testing process, as the starting point value reporting compares against. | groundrun value baseline create --output baseline.json --customer-name "Example Corp" --capture-date <date> --release-cadence 4 --qa-hours 40 --qa-days 5 --confidence-method "manual regression pass" |
groundrun value baseline validate <file> |
Check that a baseline document is well-formed. | groundrun value baseline validate baseline.json |
groundrun value release record --log <path> --version <version> --date <date> --scenarios-total <n> --scenarios-green <n> [--red-scenario <name> ...] |
Append a release's test outcome to a release log, for later reporting. | groundrun value release record --log releases.jsonl --version 1.4.0 --date <date> --scenarios-total 12 --scenarios-green 12 |
groundrun value catch record --log <path> --date <date> --domains <text> --scenario <name> --severity <text> --description <text> [--causative-date <date>] [--estimated-cost <amount>] |
Record one issue caught by a test scenario, for later reporting. | groundrun value catch record --log catches.jsonl --date <date> --domains firmware --scenario my-app/my-scenario --severity high --description "connection dropped after reset" |
groundrun value report generate --baseline <path> --results-dir <dir> --output <path> --format markdown|json|both [--release-log <path>] [--catch-log <path>] [--report-date <date>] [--hourly-rate <amount>] [--period-months <n>] |
Generate a value report from a baseline, a directory of run results, and optional release/catch logs. | groundrun value report generate --baseline baseline.json --results-dir ./results --output value-report.md --format markdown --period-months 3 |