CLI Reference

nvcrectl workloadrun

View as Markdown

nvcrectl workloadrun run

Applies a WorkloadRun manifest to the cluster and optionally waits for completion.

$nvcrectl workloadrun run [flags] <file>

Flags

FlagDefaultDescription
--waitfalseBlock until the workload completes
--timeout30mTimeout for --wait
--setupfalseInstall CRDs, controller, and LogProfiles before creating the WorkloadRun
--cleanupfalseDelete the WorkloadRun and installed components after completion
--image—Override controller image
--controller-pull-secret—Token for controller registry auth during --setup (e.g. GitHub PAT for ghcr.io) — separate from workload image credentials
--workload-registry—Registry server for workload image pull (e.g. nvcr.io, ghcr.io) — required when --workload-registry-password is set
--workload-registry-username—Registry username for workload image pull (e.g. $oauthtoken for NGC) — required when --workload-registry-password is set
--workload-registry-password—Registry password or API key — creates an nvcrectl-pull-<name> imagePullSecret in the namespace, deleted automatically when the WorkloadRun is deleted
--name—Override the WorkloadRun name
--node-list—Comma-separated list of nodes to target
--topology-domain—Topology domain to target
--topology-key—Node label key for topology grouping
--test-scale—Override testScale (intra-node, intra-rack, full-scale)
--results-file—Write results as JSON to this file path (requires --wait)

Examples

$nvcrectl workloadrun run --wait my-workload.yaml

Pull workload images from NGC:

$nvcrectl workloadrun run \
>  --workload-registry nvcr.io \
>  --workload-registry-username '$oauthtoken' \
>  --workload-registry-password "$NGC_API_KEY" \
>  --wait my-workload.yaml

nvcrectl workloadrun render

Renders the Workflow that would be created from a WorkloadRun, without applying it. Useful for offline inspection.

$nvcrectl workloadrun render [flags] <workloadrun.yaml>

Flags

FlagDefaultDescription
--platformautoOverride platform detection (aws, gcp, azure, oci, onprem, togetherai, mistral, forge, nscale)
--dry-runfalseConnect to cluster, discover real nodes, and render with actual platform/GPU detection
--outputyamlOutput format: yaml or json

nvcrectl workloadrun report

Generates a report for a completed WorkloadRun, including bandwidth and goodput metrics if configured.

$nvcrectl workloadrun report <name> [flags]

Flags

FlagDefaultDescription
--results-file—Write report as JSON to this file path
--output / -otextOutput format: text or json

nvcrectl workloadrun status

Prints the current status of a WorkloadRun.

$nvcrectl workloadrun status <name> [flags]

Flags

FlagDefaultDescription
--output / -otextOutput format: text or json

nvcrectl workloadrun cancel

Cancels one or more running WorkloadRuns.

$nvcrectl workloadrun cancel <name> [<name>...]