documentation

Command reference

Every bud_runner command and its core options, with the environment variables and files the runner uses.

All commands are invoked as python -m bud_runner <command>. The core options for each:

run-tests      -t, --test-case-list TEXT        module path to a list attribute (required)
               -o, --output, --junit-report     JUnit XML [default: report_junit.xml]
               -f, --format [json|text|junit]   output format [default: junit]
               --continue-on-error/--stop-on-error
               -b, --backend-url TEXT
               -u, --username / --password       token refresh during uploads
               --test-run-id INT                 attach to an existing TestRun
               --upload/--no-upload              [default: upload]
               --test-timeout INT                per test [default: 300]
               --suite-timeout INT               full suite [default: 1800]
               -A, --artifact TEXT               file or glob uploaded with the
                                                 results; repeatable
               --artifact-dir PATH               directory uploaded if present
                                                 [default: bud-artifacts]

claim-run      -b, --backend-url TEXT            backend to claim runs from
               -u, --username TEXT               runner account to claim as
               --workspace PATH                  station's test modules
                                                 [default: current directory]
               --interval INT                    seconds between polls;
                                                 0 claims once and exits
               -A, --artifact TEXT               uploaded with each claimed run;
                                                 repeatable
               --test-timeout INT                per test [default: 300]
               --suite-timeout INT               full suite [default: 1800]

add-test-run   -t, --test-case-list TEXT        (required)
               -n, --test-suite-name TEXT        (required)
               --url-test-software / --ref-test-software
               --sw-under-test / --ref-sw-under-test
               --product-composition-id INT      [default: 1]
               --status TEXT                     [default: Running]

register       -u, --username TEXT               (required)
               -p, --password TEXT               (auto-generated if omitted)
               --socket-port INT                 [default: 53035]
               --api-key TEXT                    station enrolment key; falls back to RUNNER_API_KEY
               --re-register

list-tests     -t, --test-case-list TEXT        resolve a list without running it
status         -b, --backend-url TEXT            config, /api/health, /api/version
daemon         -i, --interval INT [60]  -p, --port INT  --bind-host [127.0.0.1]  -l, --location
version        show bud_runner version

Typer shell completion is available via bud-runner --install-completion.

Commands

run-tests

Resolves a test case list from a module attribute (a list of "module.ClassName" strings), executes each case, and writes a JUnit report. Each test class runs in its own OS process. --test-timeout bounds one test and --suite-timeout the whole suite, in seconds.

Uploads are enabled by default. Use --no-upload for local runs. On a 401 Unauthorized with --username and --password supplied, the runner re-authenticates and retries once. If the upload still fails, it exits non-zero and spools the payload under ~/.bud/spool/results/ for replay on the next successful run. See Run and upload and Uploading artifacts.

claim-run

Pulls runs scheduled in Bud and executes them from --workspace. With --interval 0 it claims once and exits, the form to use from cron or a CI job. Its --artifact patterns are forwarded to each claimed run. See Backend-queued runs.

add-test-run

Adds a test run to Bud for a test case list and a test suite name, with optional references to the test software and the software under test. run-tests --test-run-id attaches results to an existing test run.

register

Registers this host as a Test Station with a station enrolment key, passed with --api-key or read from RUNNER_API_KEY. If --password is omitted, the runner generates one and prints it once. Use --re-register with the existing password to refresh the token or update socket settings. register also accepts --no-start. See Register a runner.

list-tests

Resolves a test case list without running it.

status

Shows the runner configuration and checks the backend’s /api/health and /api/version.

daemon

Runs the long-lived runner: heartbeat plus a local control socket, bound to 127.0.0.1 by default. daemon also accepts --username. See Daemon.

version

Shows the bud_runner version.

Environment variables

Variable	Used for
`BUD_BACKEND_URL`	The Bud instance, instead of `--backend-url`
`RUNNER_API_KEY`	The station enrolment key for `register`, instead of `--api-key`
`BUD_TOKEN`	An API token, for example from a CI secret

Files

Path	Holds
`~/.bud/config.json`	The machine vault: secret tokens and daemon settings
`app.properties`	Project metadata in your repository: `budRunnerAccount`, `budBackend`
`~/.bud/daemons/`	Daemon logs and PIDs, prefixed `bud_<username>`
`~/.bud/spool/results/`	Result payloads that failed to upload, replayed on the next successful run