How to run

vast config

Manage run configuration.

vast config [OPTIONS] COMMAND [ARGS]...

generate

Generate run configurations and output files.

Creates all configurations and associated files in the configured results directory.

Requires project initialization with vast init first.

vast config generate [OPTIONS] OUTPUT_DIR

Options

--keep-transient

Keep and display temporary folders used during generation (e.g. by FloorplanGeneration).

--no-cache

Skip cache lookup and force a fresh generation even if inputs are unchanged.

Arguments

OUTPUT_DIR

Required argument

variation-points

List possible variation points from the scenario files.

Shows all available variation points (scenario parameters) that can be varied in the scenarios as defined in the vast configuration file.

Requires project initialization with vast init first.

vast config variation-points [OPTIONS]

variation-types

List available variation types.

Shows all registered variation type entry points that can be used in the variations section of .vast configuration files.

vast config variation-types [OPTIONS]

list

List scenario configs without generating files.

This command shows all configs that would be generated from the configuration file without actually creating the output files.

Requires project initialization with vast init first.

vast config list [OPTIONS]

Options

--debug

Show internal values starting with _

vast exec

Execute scenarios locally or on a cluster.

Run scenario configurations either locally using Docker or on a Kubernetes cluster for distributed execution.

vast exec [OPTIONS] COMMAND [ARGS]...

local

Execute scenarios locally using Docker.

Run run configurations in Docker containers with bind mounts for configuration and output data.

Requires project initialization with vast init first.

vast exec local [OPTIONS] COMMAND [ARGS]...

prepare-run

Prepare run without executing.

Generates all necessary configuration files and a run.sh script for manual execution. This is useful for inspecting the generated configuration, debugging, or executing scenarios with custom modifications.

This command does NOT execute the scenario - it only prepares the files. Use vast execution local run for immediate execution.

Prerequisites: - Project initialized with vast init

Generated files in OUTPUT-DIR: - config/: Directory containing all scenario configuration files - run.sh: Executable shell script to run the scenario with Docker - Various temporary configuration files for the execution

After preparation, inspect the files in OUTPUT-DIR and execute manually cd OUTPUT-DIR; ./run.sh.

The run.sh script supports the same options as vast execution local run (–start-only, –no-gui, –network-host, –output, –image, –abort-on-failure, –log-tree, –debug).

vast exec local prepare-run [OPTIONS] OUTPUT_DIR

Options

-c, --config <config>

Run only a specific configuration by name

-r, --runs <runs>

Override the number of runs specified in the config

--use-resource-allocation

Add CPU/memory reservations to docker compose run (default: skip for local)

-t, --log-tree

Log scenario execution live tree

-d, --debug

Enable scenario execution debug output

Arguments

OUTPUT_DIR

Required argument

run

Execute scenario configurations locally using Docker.

Runs scenario configurations in Docker containers with bind mounts for configuration and output data. By default, runs all configurations from the project configuration and continues past failures. Use --abort-on-failure to stop at the first failure. GUI support is enabled by default (requires X11 server on host).

Prerequisites: - Docker must be installed and running - Project initialized with vast init - X11 server running on host (for GUI support, disable with --no-gui)

Output:

Results are written to the project results directory by default, or to a custom directory specified with --output.

vast exec local run [OPTIONS]

Options

-c, --config <config>

Run only configurations matching this name or glob pattern (e.g. hall*)

-r, --runs <runs>

Override the number of runs specified in the config

-o, --output <output>

Output directory (uses project results dir if not specified)

--start-only

Start the robovast container with a shell, skipping the entrypoint script

--no-gui

Disable host GUI support

--network-host

Use host network mode

-i, --image <image>

Use a custom Docker image

--abort-on-failure

Stop execution after the first failed run config (default: continue)

--use-resource-allocation

Add CPU/memory reservations to docker compose run (default: skip for local)

-t, --log-tree

Log scenario execution live tree

-d, --debug

Enable scenario execution debug output

cluster

Execute scenarios on a Kubernetes cluster.

Run scenario configurations as Kubernetes jobs with bind mounts for configuration and output data.

Requires project initialization with vast init first.

vast exec cluster [OPTIONS] COMMAND [ARGS]...

cleanup

Clean up the Kubernetes cluster setup.

Removes the NFS server pod and service from the Kubernetes cluster by deleting the NFS manifest configuration.

This command can be run after completing all scenario executions to clean up cluster infrastructure resources (different from run-cleanup which only cleans up job pods).

If --cluster-config is not specified, it will automatically detect which cluster configuration was used during setup (from the project flag file). When specifying --cluster-config explicitly, pass -n <namespace> if the setup was done in a non-default namespace.

vast exec cluster cleanup [OPTIONS]

Options

-c, --cluster-config <config_name>

Cluster configuration plugin to use (auto-detects if not specified)

-n, --namespace <namespace>

Kubernetes namespace to clean up (required when using –cluster-config without prior setup)

-o, --option <options>

Cluster-specific option in key=value format (can be used multiple times)

-x, --context <kube_context>

Kubernetes context to use (default: active context in kubeconfig)

download-cleanup

Remove result buckets from cluster S3 without downloading.

Deletes run result buckets (campaign-*) from the MinIO S3 server in the cluster.

Use –campaign to remove only a specific campaign’s bucket. Use -o key=value to pass credentials not stored in the flag file (e.g. -o gcs_access_key=<key> -o gcs_secret_key=<secret>).

vast exec cluster download-cleanup [OPTIONS]

Options

-i, --campaign <campaign>

Only remove this campaign’s bucket (e.g. campaign-2025-02-27-123456). Without this, removes all campaign buckets.

-o, --option <options>

Cluster-specific option in key=value format (e.g. gcs_access_key=<key>).

-x, --context <kube_context>

Kubernetes context to use (default: active context in kubeconfig)

monitor

Monitor scenario execution jobs on the cluster.

Displays progress per run: how many jobs have finished (completed or failed), how many are running, and how many are pending for each run.

By default, monitors only the contexts referenced in the .vast config file. Falls back to the active kubeconfig context when no per-cluster config is defined. Use –context to restrict monitoring to a single cluster. Only contexts with active or past jobs are shown.

This is intended for monitoring jobs created by vast execution cluster run.

vast exec cluster monitor [OPTIONS]

Options

-i, --interval <interval>

Polling interval in seconds

Default:

2.0

--once

Print job status once and exit

-x, --context <kube_context>

Kubernetes context to use (default: active context in kubeconfig)

prepare-run

Prepare complete setup for manual deployment.

Generates all necessary files for cluster execution and writes them to the specified output directory.

The output directory will contain: - kueue-queue-setup.yaml and README_kueue.md — Kueue queue manifests and setup instructions - config/ directory with all scenario configurations - jobs/ directory with individual job manifest YAML files - all-jobs.yaml file with all jobs combined - upload_configs.py script to upload run configurations to the cluster - README.md with general execution instructions - Cluster-specific setup files (manifests, templates, README)

The generated package is self-contained and can be used to: 1. Set up Kueue (job queueing) — follow README_kueue.md 2. Set up the cluster infrastructure (MinIO S3 server, PVCs) 3. Upload configuration files to the cluster 4. Deploy and execute all scenario jobs

Cluster-specific options can be passed using –option key=value.

Requires project initialization with vast init first.

vast exec cluster prepare-run [OPTIONS] OUTPUT

Options

-c, --config <config>

Prepare only a specific config by name

-r, --runs <runs>

Override the number of runs specified in the config

-k, --cluster-config <cluster_config>

Override the cluster configuration specified in the config

-o, --option <options>

Cluster-specific option in key=value format (can be used multiple times)

-t, --log-tree

Log scenario execution live tree

-x, --context <kube_context>

Kubernetes context to use (default: active context in kubeconfig)

Arguments

OUTPUT

Required argument

run

Execute scenarios on a Kubernetes cluster.

Deploys all run configurations (or a specific one) as Kubernetes jobs for distributed parallel execution.

By default, exits immediately after creating jobs. Use –follow to wait for all jobs to complete before returning. Use –cleanup to remove previous runs before starting (by default, previous runs are left intact so multiple runs can run in parallel). Use ‘vast execution cluster run-cleanup’ to clean up jobs afterwards. Use –context to target a specific Kubernetes cluster.

Requires project initialization with vast init first.

vast exec cluster run [OPTIONS]

Options

-c, --config <config>

Run only configurations matching this name or glob pattern (e.g. hall*)

-r, --runs <runs>

Override the number of runs specified in the config

-f, --follow

Follow job execution and wait for completion (default: exit immediately after creating jobs)

--cleanup

Clean up previous runs before starting (default: do not cleanup; allows multiple parallel runs)

-t, --log-tree

Log scenario execution live tree

-x, --context <kube_context>

Kubernetes context to use (default: active context in kubeconfig)

run-cleanup

Clean up jobs and pods from a cluster run.

Removes scenario execution jobs and their associated pods. By default removes all campaigns. Use –campaign to clean only a specific run.

Useful after running with –detach to clean up resources once jobs have completed.

Use --data to also delete the S3 result bucket(s) from the cluster MinIO server (equivalent to additionally running download-cleanup). Requires the robovast pod to be running.

Use -o key=value to pass credentials that are not stored in the flag file (e.g. -o gcs_access_key=<key> -o gcs_secret_key=<secret>). Only needed together with --data when GCS credentials are missing.

Usage: vast execution cluster run-cleanup Usage: vast execution cluster run-cleanup –campaign campaign-2025-02-27-123456 Usage: vast execution cluster run-cleanup –campaign campaign-2025-02-27-123456 –data Usage: vast execution cluster run-cleanup –data -o gcs_access_key=<key> -o gcs_secret_key=<secret>

vast exec cluster run-cleanup [OPTIONS]

Options

-i, --campaign <campaign>

Clean only jobs for this campaign (e.g. campaign-2025-02-27-123456). Without this, cleans all scenario-runs jobs.

--data

Also remove the campaign S3 result bucket(s) from the cluster MinIO server.

-o, --option <options>

Cluster-specific option in key=value format (e.g. gcs_access_key=<key>). Used with –data when credentials are not stored in the flag file.

-x, --context <kube_context>

Kubernetes context to use (default: active context in kubeconfig)

setup

Set up the Kubernetes cluster for execution.

Deploys a MinIO S3 server in the Kubernetes cluster. The server is used to store run configurations and results for individual scenario execution jobs.

This command should be run once before executing scenarios on the cluster for the first time.

If the cluster is already set up, this command will exit with an error. Run ‘vast execution cluster cleanup’ first to clean up the existing setup, or use --force to force re-setup.

Use --list to see available cluster configuration plugins.

Cluster-specific options can be passed using --option key=value.

Node label selectors for job and control pods are read from the .vast config file under execution.kubernetes.jobs.node_labels and execution.kubernetes.control.node_labels.

vast exec cluster setup [OPTIONS] [CLUSTER_CONFIG]

Options

--list

List available cluster configuration plugins

-n, --namespace <namespace>

Kubernetes namespace for execution (used by cluster run)

Default:

default

-o, --option <options>

Cluster-specific option in key=value format (can be used multiple times)

-f, --force

Force re-setup even if cluster is already set up

-x, --context <kube_context>

Kubernetes context to use (default: active context in kubeconfig)

Arguments

CLUSTER_CONFIG

Optional argument

upload-to-share

Upload campaign archives from the cluster pod to a remote share service.

Results are transferred entirely inside the archiver sidecar of the robovast pod — no data is downloaded to the local machine.

Use --campaign (-i) to upload a single campaign. If the specified campaign is not found, available campaigns are listed.

For each available run the command:

1. Creates a compressed tar.gz archive in the pod.

Skips this step if the archive already exists.

2. Uploads the archive to the configured share service from inside the pod.

3. Removes the archive from the pod on success (unless --keep-archive).

4. Keeps the S3/GCS campaign data (use --remove-from-storage to delete it).

5. Keeps both the archive and the bucket if the upload fails so you can

retry.

Configuration is read from a .env file in the current or any parent directory. Required variables:

ROBOVAST_SHARE_TYPE — share provider: nextcloud, gcs, sftp, webdav

Additional variables depend on the share type. Run with no .env file to see a list of required variables for the detected share type.

Use --keep-archive to retain the archive in the pod after upload (useful when you want to also download the results locally later).

vast exec cluster upload-to-share [OPTIONS]

Options

-i, --campaign <campaign>

Only upload this campaign (e.g. campaign-2025-02-27-123456). Can be specified multiple times. Without this, uploads all campaigns.

-f, --force

Force recreation of the remote tar.gz archive even if it already exists

-v, --verbose

Print detailed progress

--keep-archive

Keep the tar.gz in the pod /data/ after a successful upload

--remove-from-storage

Delete the campaign data from S3/GCS after a successful upload. Without this flag, data is kept in storage.

-x, --context <kube_context>

Kubernetes context to use (default: active context in kubeconfig)

vast results

Manage run results.

Tools for postprocessing scenario execution results, including data conversion, merging, and metadata generation.

vast results [OPTIONS] COMMAND [ARGS]...

postprocess

Run postprocessing commands on run results.

Executes postprocessing commands defined in the .vast file found in the most recent <campaign-name>-<timestamp>/_config/ directory of the results directory. Postprocessing is skipped if the result-directory is unchanged, unless –force is specified.

Use –override to supply a .vast file explicitly instead of the campaign copy.

Requires project initialization with vast init first (unless --results-dir is specified).

vast results postprocess [OPTIONS]

Options

-r, --results-dir <results_dir>

Directory containing run results (uses project results dir if not specified)

-f, --force

Force postprocessing even if results directory is unchanged (bypasses caching)

-o, --override <VAST_FILE>

Override the .vast file used for postprocessing instead of the one found in <campaign-name>-<timestamp>/_config/

--debug

Show full plugin output (stdout) for each postprocessing step.

--skip-rosout

Skip rosout bag processing.

--skip <PLUGIN>

Skip a postprocessing plugin defined in the .vast file (e.g. –skip rosbags_to_webm). Can be specified multiple times.

--skip-db

Skip data.db creation.

--skip-metadata

Skip metadata.yaml generation.

merge-campaigns

Merge campaign directories with identical configs into one merged_campaign_dir.

Groups campaign-directory/config-directory by config_identifier from config.yaml. Run folders (0, 1, 2, …) from all campaigns are renumbered and copied. Original campaign directories are not modified.

Requires project initialization with vast init first (unless --results-dir is specified).

vast results merge-campaigns [OPTIONS] MERGED_CAMPAIGN_DIR

Options

-r, --results-dir <results_dir>

Source directory containing run-* directories (uses project results directory if not specified)

Arguments

MERGED_CAMPAIGN_DIR

Required argument

postprocess-commands

List all available postprocessing command plugins.

Shows plugin names that can be used in the results_processing.postprocessing section of the configuration file, along with their descriptions and parameters.

vast results postprocess-commands [OPTIONS]

vast eval

Evaluate and visualize run results.

Tools for interactive exploration and visualization of scenario execution results using Jupyter notebooks.

vast eval [OPTIONS] COMMAND [ARGS]...

gui

Launch the graphical run results gui.

Opens a GUI application for interactive exploration and visualization of run results. Automatically runs postprocessing before launching the GUI.

Use the global -V flag to supply a .vast file explicitly instead of the campaign copy: vast -V my.vast eval gui

Requires project initialization with vast init first (unless --results-dir is specified).

vast eval gui [OPTIONS]

Options

-r, --results-dir <results_dir>

Directory containing run results (uses project results dir if not specified)

-f, --force

Force postprocessing even if results directory is unchanged (bypasses caching)

--skip-postprocessing

Skip postprocessing before launching the GUI

Environment variables

ROBOVAST_INSECURE_SSL

Set to 1 to disable TLS certificate verification for remote fetches. This allows the CLI to continue when a remote host presents an invalid certificate. Use only with hosts you trust.