CLI reference#

Choose a command for validation, execution, prerequisite installation, or report regeneration. For a complete first run, follow Run your first experiment.

CloudAI Modes Usage Examples#

The following are the global options for the cloudai command:

  • --log-file <path>: specify a file to log output; by default debug.log in the current directory is used. Contains log entries of level DEBUG and higher

  • --log-level <level>: specify logging level for standard output; default is INFO

Available Modes#

Usage Examples#

run#

This mode runs workloads. It automatically installs prerequisites if they are not met.

cloudai run\
    --system-config conf/common/system/example_slurm_cluster.toml\
    --test-scenario conf/experimental/quickstart/nccl.toml

dry-run#

This mode generates workload commands without executing the workload. This is useful for verifying configurations and testing experiment setups.

cloudai dry-run\
    --system-config conf/common/system/example_slurm_cluster.toml\
    --test-scenario conf/experimental/quickstart/nccl.toml

generate-report#

This mode generates reports under the scenario directory. It automatically runs as part of the run mode after experiments are completed.

cloudai generate-report\
    --system-config conf/common/system/example_slurm_cluster.toml\
    --test-scenario conf/experimental/quickstart/nccl.toml\
    --result-dir /path/to/result_directory

Generated artifacts depend on the scenario contents:

  • <scenario>.html summarizes scenario status.

  • <scenario>-dse-report.html describes configuration searches when the scenario contains DSE test cases.

  • <dse-case>/<iteration>/<dse-case>.toml contains the best discovered test configuration for a DSE case.

  • Workload and custom reporters may produce additional artifacts.

The Read results and generate reports guide describes experiment.json, which records execution status and workload metrics independently of reporter settings.

install#

This mode installs test prerequisites. For more details, refer to the Prepare workload prerequisites guide. It automatically runs as part of the run mode if prerequisites are not met.

cloudai install\
    --system-config conf/common/system/example_slurm_cluster.toml\
    --test-scenario conf/experimental/quickstart/nccl.toml

uninstall#

This mode is the opposite of the install mode. This mode removes installed test prerequisites.

cloudai uninstall\
    --system-config conf/common/system/example_slurm_cluster.toml\
    --test-scenario conf/experimental/quickstart/nccl.toml

list#

This mode lists internal components available within CloudAI.

cloudai list <component_type>

verify-configs#

This mode verifies the correctness of system, test, and test scenario configuration files.

# verify all at once
cloudai verify-configs conf

# verify a single file
cloudai verify-configs conf/common/system/example_slurm_cluster.toml

# verify all scenarios using specific folder with Test TOMLs
cloudai verify-configs --tests-dir conf/release/spcx/l40s/test conf/release/spcx/l40s/test_scenario