Using rtf remote
The rtf remote subcommands interact with the RTF Orchestrator Service. Most interactions with
the Orchestrator are best carried out using the Orchestrator UI: the rtf CLI is intended for
triggering runs from scripts and agents, and for pulling run output to the local machine. This page
summarizes each subcommand. For every flag, see the CLI reference.
Authentication
All subcommands except prepare authenticate with the Orchestrator through Google IAP and require:
- Access to the Orchestrator (see Orchestrator internal processes)
- Application default credentials from
gcloud auth application-default login
On first use, the CLI opens a browser window to complete sign-in and caches the resulting token.
Environment variables
| Variable | Description |
|---|---|
RTF_ORCHESTRATOR_URL | Orchestrator base URL. Defaults to the production Orchestrator. |
GITHUB_TOKEN | GitHub token used by --github to fetch the Test Plan locally. |
Triggering runs
| Subcommand | Arguments | Description |
|---|---|---|
run | <test-plan-path> [--github] [--ref <ref>] | Triggers a Test Run. Prints the Test Run ID and a UI link. |
ci-run | <test-plan-path> [--github] [--ref <ref>] [--poll-interval-seconds <n>] | Triggers a Test Run and polls until it completes. |
run-known | <test-plan-uuid> [--ref <ref>] | Triggers a Known Test Plan. Prints the Test Run ID and a UI link. |
ci-run-known | <test-plan-uuid> [--ref <ref>] [--poll-interval-seconds <n>] | Triggers a Known Test Plan and polls until it completes. |
prepare | <test-plan-path> [--github] [--ref <ref>] | Writes the Trigger Payload for a Test Plan to stdout. |
--var <key>=<value>and--vars <file.json>set Test Plan variables for these subcommands.--githubreads<test-plan-path>as<org>/<repo>/<path>and fetches the Test Plan from GitHub on the local machine before submitting it.- For
run-knownandci-run-known,--refoverrides the Known Test Plan’s default branch. --poll-interval-secondsdefaults to10.- Runs triggered with
runandci-runalways execute in the default Workload Pool.
ci-run and ci-run-known exit with:
| Exit code | Meaning |
|---|---|
0 | All executions succeeded |
1 | At least one execution failed |
2 | The run was unrunnable or was cancelled |
Pulling output
Output is only retained for a limited time; once it has expired, the commands that download or print it fail for the affected executions.
| Subcommand | Arguments | Description |
|---|---|---|
run-output | <run-id> [--outdir <dir>] [--force] | Downloads the run summary, and each execution’s log.txt and output.zip. |
execution-output | <execution-id> [--outdir <dir>] [--force] | Downloads an execution’s summary, log.txt, and output.zip. |
execution-log | <execution-id> | Prints an execution’s log.txt. |
run-status | <run-id> [--with-executions] | Prints the Test Run Summary as JSON. |
execution-status | <execution-id> | Prints a Test Execution summary as JSON. |
--outdir defaults to output. --force removes an existing output directory first.
run-output writes:
<outdir>/
run-summary.json
<execution-name>/
log.txt
output.zip
Cancelling a run
Runs are normally cancelled from their page in the Orchestrator UI. To cancel a run from the CLI,
use rtf remote request:
rtf remote request -X POST -d '{"id": "<run-id>"}' admin/purge-run
See Limits, permissions, and concepts for who is able to cancel a run.