Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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:

On first use, the CLI opens a browser window to complete sign-in and caches the resulting token.

Environment variables

VariableDescription
RTF_ORCHESTRATOR_URLOrchestrator base URL. Defaults to the production Orchestrator.
GITHUB_TOKENGitHub token used by --github to fetch the Test Plan locally.

Triggering runs

SubcommandArgumentsDescription
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.
  • --github reads <test-plan-path> as <org>/<repo>/<path> and fetches the Test Plan from GitHub on the local machine before submitting it.
  • For run-known and ci-run-known, --ref overrides the Known Test Plan’s default branch.
  • --poll-interval-seconds defaults to 10.
  • Runs triggered with run and ci-run always execute in the default Workload Pool.

ci-run and ci-run-known exit with:

Exit codeMeaning
0All executions succeeded
1At least one execution failed
2The 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.

SubcommandArgumentsDescription
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.