Cluster Validation Suite (CVS) command-line interface (CLI) reference

2026-09-24

5 min read time

Applies to Linux

Top-level commands

Command	Description
cvs generate	Generate configuration files or templates.
cvs config	Browse and copy bundled configuration templates.
cvs run	Run a test suite (wrapper over pytest).
cvs list	List available tests.
cvs monitor	Cluster health monitoring.
cvs exec	Execute a command on all cluster nodes.
cvs scp	Copy files to cluster nodes in parallel.

cvs generate

Run cvs generate with no arguments to list available generators.

Subcommands: cluster_json, heatmap.

cluster_json

Generate a cluster JSON file from a host list.

Required options (one host source plus credentials):

Option	Description
--input_hosts_file PATH or --hosts HOSTS	Host list: file with one IP/hostname per line, or comma-separated list. Supports ranges such as 192.168.1.10-20 and hostname[1-10].
--output_json_file PATH	Output cluster JSON path.
--username USER	SSH username for cluster nodes.
--key_file PATH	SSH private key file.

Optional:

Option	Description
--head_node IP	Head node IP (defaults to the first host)

See Configure the Cluster Validation Suite (CVS) cluster file (cluster.json).

heatmap

Generate an RCCL performance heatmap HTML report from actual vs reference JSON.

Required options:

Option	Description
-a PATH, --actual PATH	Actual results JSON (RCCL graph format).
-r PATH, --reference PATH	Golden reference JSON.

Optional options:

Option	Description
-o PATH, --output PATH	Output HTML path (default: /tmp/rccl_heatmap_<timestamp>.html).
-t TITLE, --title TITLE	Chart title (default: RCCL Performance Heatmap).
--metadata	Include metadata table (actual JSON must have a metadata key).
--no-data-table	Omit the data table from the HTML report.

See Run CVS RCCL performance and regression tests.

cvs config

Subcommands: list-dirs, list, copy.

list-dirs [path]

List config directories grouped by category (config_file_dirs:, cluster_file_dirs:, env_file_dirs:). Optional path scopes to a subtree (for example training).

list [path]

List template files grouped by parent directory. Optional path scopes to a subdirectory or file prefix (for example platform, rccl).

copy [path] --output PATH

Copy bundled templates into your workspace.

Option	Description
--output PATH	Destination file or directory (required).
--all	Copy all templates, preserving directory structure.
--force	Overwrite existing destination files.

Positional path is optional: omit for bulk operations with --all; specify a template path for a single-file copy (for example platform/host_config.json).

See Configure Cluster Validation Suite (CVS) test suite configuration files and Configure the Cluster Validation Suite (CVS) cluster file (cluster.json).

cvs run

Positional arguments: test [function ...] — suite name and optional test function names.

Required options:

Option	Description
--cluster_file PATH	Cluster JSON (nodes, SSH credentials, backend).
--config_file PATH	Suite-specific test configuration JSON.

Optional options:

Option	Description
--workspace PATH	Shared-filesystem root; run dir is <workspace>/cvs_runs/<run_id>. Falls back to $CVS_WORKSPACE, then the venv parent directory.
--html PATH	Pytest HTML report output path.
--self-contained-html	Embed CSS and images in the HTML report.
--log-file PATH	Text log file (parent directories created automatically).
--log-level LEVEL	DEBUG, INFO, WARNING, ERROR, CRITICAL.
--capture MODE	no, tee-sys, tee-merged, fd, sys.

All other pytest flags pass through. Run pytest --help for the full list.

See Run Cluster Validation Suite (CVS) test suites on AMD Instinct GPU clusters.

cvs list

Positional argument: [test] — optional suite name.

Optional options:

Option	Description
--cluster_file PATH	Cluster file for parameterized test collection.
--config_file PATH	Config file for parameterized test collection.

With no arguments, lists all suites (same catalog as cvs run with no arguments). With a suite name, lists test functions in that suite.

See Run Cluster Validation Suite (CVS) test suites on AMD Instinct GPU clusters.

cvs monitor

Run cvs monitor with no arguments to list available monitors.

Subcommand: check_cluster_health

Option	Description
--cluster_file PATH	Cluster JSON (recommended; takes precedence over CLUSTER_FILE).
--iterations N	Number of check iterations.
--time_between_iters SECONDS	Sleep between iterations.
--report_file PATH	Output HTML report path (default: cluster_report.html in the current directory).

Deprecated (use --cluster_file instead): --hosts_file, --username, --password, --key_file.

See Health reports and Live dashboards.

cvs exec

Required options:

Option	Description
--cmd COMMAND	Shell command to run on selected nodes.

Optional options:

Option	Description
--cluster_file PATH	Cluster JSON (or set CLUSTER_FILE).
--target {computes,switches,all}	computes (default), switches, or both.
--timeout SECONDS	Per-node command output timeout (default: 30).
--connect-timeout SECONDS	Per-node SSH connect timeout (default: 15).
--json	Emit structured JSON on stdout.
--verbose, -v	Show SSH connection diagnostics.

See Run ad-hoc commands across all Cluster Validation Suite (CVS) cluster nodes via SSH.

cvs scp

Required options:

Option	Description
--file PATH	Local file or directory to copy.

Optional options:

Option	Description
--dest PATH	Remote destination (defaults to the same path as the source).
--recurse	Copy directories recursively.
--cluster_file PATH	Cluster JSON (or set CLUSTER_FILE).
--parallel N	Parallel SCP operations (default: 20).

See Copy files to all cluster nodes using Cluster Validation Suite (CVS) parallel SCP for more information.