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

Command-Line Help for rtf

This document contains the help content for the rtf command-line program.

Command Overview:

rtf

A swiss army knife for testing the Apollo Runtime

Usage: rtf [OPTIONS] <COMMAND>

Subcommands:
  • run — Check and run a test plan
  • docs — Open the RTF documentation in your browser
  • expand-matrix — Expand a test plan matrix into JSON
  • template — Template a test plan using provided variables, outputting the resulting config to stdout
  • custom-provider — Work directly with custom file provider definitions
  • inline — Inline file providers in a test plan. Outputs the resulting test plan to the given directory
  • resolve — Resolve file providers for a config file without executing it
  • completion — Write a shell completion file to STDOUT for the given shell
  • json-schemas — Output json schemas for environment configuration
  • remote — Interactions with the RTF Orchestrator Service
  • version — Display CLI version and exit
Options:
  • --var <VAR> — A single additional templating variable in the form “key=value”
  • --vars <VARS> — Path to a JSON file containing additional template variables
  • -v, --verbose — Flag to control logging verbosity. Default level is warn. -v sets logging level to info,-vv to debug and -vvv to trace

rtf run

Check and run a test plan

Usage: rtf run [OPTIONS] <TEST_PLAN_PATH>

Arguments:
  • <TEST_PLAN_PATH> — Relative path to the test plan file that should be executed. When using –github this must be in the format ORG/REPO/PATH
Options:
  • --environment-up — Only run the environment setup

  • --environment-down — Only run the environment teardown

  • --scenario — Only run the environment scenario

  • --github — Execute a test plan file in GitHub instead of from a local path

    Default value: false

  • --ref <GIT_REF> — Optional git ref to pull files from when using –github

  • --outdir <OUTDIR> — Output directory for providers when they run

    Default value: output

  • --force — Force removal of an existing output directory before running

    Default value: false

rtf docs

Open the RTF documentation in your browser

Usage: rtf docs [SEARCH_TERM]...

Arguments:
  • <SEARCH_TERM> — An optional search term to search for within the docs

rtf expand-matrix

Expand a test plan matrix into JSON

Usage: rtf expand-matrix [OPTIONS] <TEST_PLAN_PATH>

Arguments:
  • <TEST_PLAN_PATH> — Relative path to the test-plan.yaml file that should have its matrix expanded
Options:
  • -c, --compact — Return the expanded matrix JSON in compact form

rtf template

Template a test plan using provided variables, outputting the resulting config to stdout

Usage: rtf template [OPTIONS] <TEST_PLAN_PATH>

Arguments:
  • <TEST_PLAN_PATH> — Relative path to the test plan file that should be templated. When using –github this must be in the format ORG/REPO/PATH
Options:
  • --check — Run a static check of the resulting test plan after templating

  • --github — Template a test plan file from GitHub instead of from a local path

    Default value: false

  • --ref <GIT_REF> — Optional git ref to pull files from when using –github

rtf custom-provider

Work directly with custom file provider definitions

Usage: rtf custom-provider <COMMAND>

Subcommands:
  • template — Template a custom provider definition, outputting the resulting config to stdout
  • run — Execute a custom provider definition

rtf custom-provider template

Template a custom provider definition, outputting the resulting config to stdout

Usage: rtf custom-provider template [OPTIONS] <DEFINITION_PATH>

Arguments:
  • <DEFINITION_PATH> — Relative path to the custom provider definition file
Options:
  • --check — Run a static check of the resulting test plan after templating

rtf custom-provider run

Execute a custom provider definition

Usage: rtf custom-provider run [OPTIONS] <DEFINITION_PATH>

Arguments:
  • <DEFINITION_PATH> — Relative path to the custom provider definition file
Options:
  • --outdir <OUTDIR> — Output directory for provider execution

    Default value: output

  • --force — Force removal of an existing output directory before running

    Default value: false

rtf inline

Inline file providers in a test plan. Outputs the resulting test plan to the given directory

Usage: rtf inline <COMMAND>

Subcommands:
  • all — Inline all file providers
  • relative-files — Inline only relative file providers

rtf inline all

Inline all file providers

Usage: rtf inline all [OPTIONS] <TEST_PLAN_PATH>

Arguments:
  • <TEST_PLAN_PATH> — Relative path to the test-plan.yaml file that should be inlined. When using –github this must be in the format ORG/REPO/PATH
Options:
  • --outdir <OUTDIR> — Output directory for inlined test plan

    Default value: output

  • --force — Force removal of an existing output directory before running

    Default value: false

  • --github — Inline a test plan file from GitHub instead of from a local path

    Default value: false

  • --ref <GIT_REF> — Optional git ref to pull files from when using –github

rtf inline relative-files

Inline only relative file providers

Usage: rtf inline relative-files [OPTIONS] <TEST_PLAN_PATH>

Arguments:
  • <TEST_PLAN_PATH> — Relative path to the test-plan.yaml file that should be inlined. When using –github this must be in the format ORG/REPO/PATH
Options:
  • --outdir <OUTDIR> — Output directory for inlined test plan

    Default value: output

  • --force — Force removal of an existing output directory before running

    Default value: false

  • --github — Inline a test plan file from GitHub instead of from a local path

    Default value: false

  • --ref <GIT_REF> — Optional git ref to pull files from when using –github

rtf resolve

Resolve file providers for a config file without executing it

Usage: rtf resolve <COMMAND>

Subcommands:
  • scenario — Resolve file providers for a standalone scenario config
  • environment — Resolve file providers for a standalone environment config

rtf resolve scenario

Resolve file providers for a standalone scenario config

Usage: rtf resolve scenario [OPTIONS] <SCENARIO_PATH>

Arguments:
  • <SCENARIO_PATH> — Relative path to the scenario.yaml file
Options:
  • --outdir <OUTDIR> — Output directory for resolved providers and scenario.env

    Default value: output

  • --force — Force removal of an existing output directory before running

    Default value: false

rtf resolve environment

Resolve file providers for a standalone environment config

Usage: rtf resolve environment [OPTIONS] <ENVIRONMENT_PATH>

Arguments:
  • <ENVIRONMENT_PATH> — Relative path to the environment.yaml file
Options:
  • --outdir <OUTDIR> — Output directory for resolved providers and env files

    Default value: output

  • --force — Force removal of an existing output directory before running

    Default value: false

rtf completion

Write a shell completion file to STDOUT for the given shell

Usage: rtf completion [OPTIONS]

Options:
  • -s, --shell <SHELL> — The shell to generate completions for (defaults to identifying from the environment)

    Possible values: bash, elvish, fish, powershell, zsh

rtf json-schemas

Output json schemas for environment configuration

Usage: rtf json-schemas <CONFIG>

Arguments:
  • <CONFIG>

    Possible values: test-plan, environment, scenario

rtf remote

Interactions with the RTF Orchestrator Service.

Requests are authenticated via Google Cloud IAP. Before using these subcommands you need Orchestrator access and Google Application Default Credentials (gcloud auth application-default login). The first request opens a browser to complete an OAuth consent flow, and the resulting token is cached on disk.

Environment variables:

  • RTF_ORCHESTRATOR_URL: override the Orchestrator base URL (defaults to the production Orchestrator when unset).

Usage: rtf remote <COMMAND>

Subcommands:
  • prepare — Prepare a test plan for remote execution by the Orchestrator. Outputs an Orchestrator-compatible JSON payload with inlined relative files and custom providers
  • request — Send an IAP-authenticated HTTP request to the Orchestrator
  • run — Trigger a test run using the Orchestrator
  • run-known — Trigger a test run of a known test plan using the Orchestrator
  • ci-run — Trigger a test run using the Orchestrator and poll for the result
  • ci-run-known — Trigger a test run of a known test plan using the Orchestrator and poll for the result
  • execution-log — View the scenario log for a single test execution
  • execution-output — Pull all output for a single test execution (log, output.zip & status)
  • execution-status — View the status summary for a single test execution
  • run-output — Pull output for all executions within a given test run
  • run-status — View the status summary for a test run
  • cancel-run — Cancel a test run

rtf remote prepare

Prepare a test plan for remote execution by the Orchestrator. Outputs an Orchestrator-compatible JSON payload with inlined relative files and custom providers

Usage: rtf remote prepare [OPTIONS] <TEST_PLAN_PATH>

Arguments:
  • <TEST_PLAN_PATH> — Relative path to the test plan file. When using –github this must be in the format ORG/REPO/PATH
Options:
  • --github — Prepare a test plan file from GitHub instead of from a local path.

    The test plan is fetched and resolved locally, so this requires a GITHUB_TOKEN environment variable with read access to the repository.

    Default value: false

  • --ref <GIT_REF> — Optional git ref to pull files from when using –github

rtf remote request

Send an IAP-authenticated HTTP request to the Orchestrator.

The response body is written to stdout on success.

Usage: rtf remote request [OPTIONS] <PATH>

Arguments:
  • <PATH> — Path on the Orchestrator to request (e.g. /health)
Options:
  • -X, --method <METHOD> — HTTP method

    Default value: GET

  • -d, --body <BODY> — Request body as a literal string.

    For POST and PUT requests this must be valid JSON unless –plain-text is set.

  • --plain-text — Send the body as-is without validating it as JSON or setting a content type on POST/PUT requests

    Default value: false

rtf remote run

Trigger a test run using the Orchestrator.

The output of this command will be the test run id and a link to the RTF UI to view the status

Usage: rtf remote run [OPTIONS] <TEST_PLAN_PATH>

Arguments:
  • <TEST_PLAN_PATH> — Relative path to the test plan file. When using –github this must be in the format ORG/REPO/PATH
Options:
  • --github — Prepare a test plan file from GitHub instead of from a local path.

    The test plan is fetched and resolved locally, so this requires a GITHUB_TOKEN environment variable with read access to the repository.

    Default value: false

  • --ref <GIT_REF> — Optional git ref to pull files from when using –github

rtf remote run-known

Trigger a test run of a known test plan using the Orchestrator.

The output of this command will be the test run id and a link to the RTF UI to view the status

Usage: rtf remote run-known [OPTIONS] <TEST_PLAN_ID>

Arguments:
  • <TEST_PLAN_ID> — Known Test Plan ID from the Orchestrator.

    You can find this on the UI page providing your known Test Plan’s details.

Options:
  • --ref <GIT_REF> — Optional git ref to run the test plan from, overriding the ref registered for the known test plan

rtf remote ci-run

Trigger a test run using the Orchestrator and poll for the result.

The output of this command is aimed at being usable in CI runs and is non-interactive.

Exit codes: 0 if the run succeeded, 1 if it failed, and 2 if it was unrunnable or cancelled.

Usage: rtf remote ci-run [OPTIONS] <TEST_PLAN_PATH>

Arguments:
  • <TEST_PLAN_PATH> — Relative path to the test plan file. When using –github this must be in the format ORG/REPO/PATH
Options:
  • --github — Prepare a test plan file from GitHub instead of from a local path.

    The test plan is fetched and resolved locally, so this requires a GITHUB_TOKEN environment variable with read access to the repository.

    Default value: false

  • --ref <GIT_REF> — Optional git ref to pull files from when using –github

  • --poll-interval-seconds <POLL_INTERVAL_SECONDS> — Number of seconds to wait between polls for the status of the test run

    Default value: 10

rtf remote ci-run-known

Trigger a test run of a known test plan using the Orchestrator and poll for the result.

The output of this command is aimed at being usable in CI runs and is non-interactive.

Exit codes: 0 if the run succeeded, 1 if it failed, and 2 if it was unrunnable or cancelled.

Usage: rtf remote ci-run-known [OPTIONS] <TEST_PLAN_ID>

Arguments:
  • <TEST_PLAN_ID> — Known Test Plan ID from the Orchestrator.

    You can find this on the UI page providing your known Test Plan’s details.

Options:
  • --ref <GIT_REF> — Optional git ref to run the test plan from, overriding the ref registered for the known test plan

  • --poll-interval-seconds <POLL_INTERVAL_SECONDS> — Number of seconds to wait between polls for the status of the test run

    Default value: 10

rtf remote execution-log

View the scenario log for a single test execution

Usage: rtf remote execution-log <ID>

Arguments:
  • <ID> — ID of the Orchestrator test execution you wish to view the log of

rtf remote execution-output

Pull all output for a single test execution (log, output.zip & status)

Usage: rtf remote execution-output [OPTIONS] <ID>

Arguments:
  • <ID> — ID of the Orchestrator test execution you wish to pull output for
Options:
  • --outdir <OUTDIR> — Directory to place output in

    Default value: output

  • --force — Force removal of an existing output directory before running

    Default value: false

rtf remote execution-status

View the status summary for a single test execution

Usage: rtf remote execution-status <ID>

Arguments:
  • <ID> — ID of the Orchestrator test execution you wish to view the status of

rtf remote run-output

Pull output for all executions within a given test run

Usage: rtf remote run-output [OPTIONS] <ID>

Arguments:
  • <ID> — ID of the Orchestrator test run you wish to pull output for
Options:
  • --outdir <OUTDIR> — Directory to place output in

    Default value: output

  • --force — Force removal of an existing output directory before running

    Default value: false

rtf remote run-status

View the status summary for a test run

Usage: rtf remote run-status [OPTIONS] <ID>

Arguments:
  • <ID> — ID of the Orchestrator test run you wish to view the status of
Options:
  • --with-executions — Include details of the underlying test executions in the summary

    Default value: false

rtf remote cancel-run

Cancel a test run

Usage: rtf remote cancel-run <ID>

Arguments:
  • <ID> — ID of the Orchestrator test run you wish to cancel

rtf version

Display CLI version and exit

Usage: rtf version