CLI Reference¶
Commands¶
| Command | Description |
|---|---|
run-suite |
Load and execute a test-suite YAML file |
export-schema |
Export the bundled JSON Schema to a local file |
version |
Display the application version |
run-suite¶
The command is run-suite with alias rs.
Syntax¶
Options¶
| Option | Required | Description |
|---|---|---|
--suite=<path> |
No | Path to the test-suite YAML file. When omitted, the CLI looks for test-suite.yml in the current working directory. An error is shown if neither is found. |
--tag=<value> |
No | Run only test cases whose tag field contains this value. Prefix with ! to invert: --tag="!slow" runs all tests except those tagged slow; tests with no tags are always included under a negated filter. Cannot be used together with --test. |
--test=<name> |
No | Run only the single test case whose name field exactly matches this value. Use double quotes if the name contains spaces: --test="My Test Name". Cannot be used together with --tag. |
--no-ui |
No | Force JSON output even when stdout looks like a TTY. |
--ui |
No | Force the interactive terminal UI even when stdout does not look like a TTY. |
--report=<dir> |
No | Absolute path to a directory where the HTML execution report will be written. The filename is auto-generated as test-suite_<name>_yyyyMMddHHmmss.html. The directory is created if it does not exist. See HTML Report. |
Positional arguments (CLI variables)¶
After all named options, pass key=value tokens to inject variables into the Thymeleaf template engine:
Important: Do NOT prefix variable names with --. Any token without an = sign is silently skipped.
These variables are accessible in your YAML as [[${cli.api_base_url}]], [[${cli.admin_system}]], etc.
Mutual exclusion¶
--tag and --test cannot be used together. If both are supplied, the run aborts with an error:
Output mode selection (evaluated in order)¶
- If
--uiis supplied → interactive terminal UI is activated regardless of environment - If
--no-uiis supplied → JSON output is forced regardless of TTY - Otherwise → auto-detect based on:
- TTY attached to stdout
NO_COLORenvironment variable (disables UI if set)CIenvironment variable (disables UI if set)- Terminal width (UI disabled if below 40 columns)
Examples¶
Run test-suite.yml in the current directory (no arguments required)¶
Run all tests in an explicit suite file¶
Run only tests tagged "smoke"¶
Run all tests except those tagged "slow" (negated filter)¶
Run a single test by name¶
Pass CLI variables¶
rs --suite=/path/to/suite.yml api_url=https://staging.example.com user_name=testuser password=secret123
Force JSON output for CI¶
Force interactive UI on non-TTY (e.g., in a Docker container with TTY support)¶
Generate an HTML execution report¶
The file is written to /path/to/reports/test-suite_<suiteName>_<timestamp>.html. See
HTML Execution Report for the full description of report contents.
export-schema¶
Exports the bundled test-suite-schema.json to a local directory so you can wire it to your
test-suite YAML files for IDE validation and autocompletion.
The command is export-schema with alias es.
Syntax¶
Options¶
| Option | Required | Description |
|---|---|---|
--out=<dir> |
Yes | Absolute or relative path to the output directory. The file is always written as test-suite-schema.json inside this directory. The directory is created automatically if it does not exist. An existing file is overwritten. |
Examples¶
# Write to a local schemas/ directory (using the full command name)
export-schema --out ./schemas
# Same using the alias
es --out ./schemas
# Write to an absolute directory path
es --out /home/user/schemas
On success the command prints the absolute path of the written file:
For instructions on wiring the schema to your IDE see Schema Support.
version¶
Prints the application version. The version is read from build metadata embedded at build time by
the spring-boot-maven-plugin build-info goal, so it always reflects the version declared in
pom.xml — for both the JAR and the GraalVM native binary. The same version appears in the footer
of generated HTML reports.
The command is version (no alias) and takes no options.
Syntax¶
Example¶
Output: