cli.qmd

---
title: "CLI Reference"
toc: true
---

<!-- GENERATED FILE - do not edit by hand.
     Sources: registry/ + selection ledger + datasets.yaml + asset dossiers + draft reference results + the mlperf CLI.
     Regenerate with: python3 tools/generate_docs.py -->

The `mlperf` command is the entire user surface. This reference is generated directly from the CLI's own `--help` output, so it cannot drift from the implementation.

## mlperf

```text
usage: mlperf [-h] [--registry REGISTRY]
              {doctor,init,health,fetch,run,verify,report,package,grade,validate,audit,list,show,info,cache} ...

MLPerf EDU command harness. Defaults to the mlperf-edu suite. Common user path: init, health, list, fetch, run, report. Instructor/maintainer path: audit, validate, grade.

positional arguments:
  {doctor,init,health,fetch,run,verify,report,package,grade,validate,audit,list,show,info,cache}
    doctor              Check local environment and registry
    init                Prepare local caches for a profile
    health              Verify every min path and generate the suite health
                        report
    fetch               Fetch or verify assets for workloads
    run                 Run workloads by profile, suite, or workload id
    verify              Verify a provenance manifest
    report              Print a compact report summary
    package             Package a verified submission
    grade               Grade a submission directory, manifest, or package
    validate            Run bundled validation presets
    audit               Audit the public result contract
    list                List workloads
    show                Show one workload
    info                Show suite, profile, workload, model, dataset, or run
                        details
    cache               Inspect and verify local MLPerf EDU assets

options:
  -h, --help            show this help message and exit
  --registry REGISTRY   Path to workloads.yaml. Defaults to the nearest
                        project registry.

Common user commands:
  doctor   check this machine
  init     prepare caches and optionally smoke-test the setup
  health   verify every min path and generate the suite health report
  list     discover workloads
  fetch    download or verify needed assets
  audit    check source, license, dataset, model, and quality metadata
  run      run a workload, suite, or default profile
  report   export or explicitly open a result

Instructor and maintainer commands:
  validate run validation presets that execute workloads and grade artifacts
  audit    check public-result metadata without running workloads
  grade    grade a submissions directory
  verify   verify one provenance manifest
  package  bundle a verified submission
```

## mlperf doctor

```text
usage: mlperf doctor [-h]
                     [--suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement} |
                     --workload WORKLOAD |
                     --collection {starter,standard,research,all}]
                     [--profile {min,max,pro}] [--variant VARIANT]
                     [--format {summary,json}]

options:
  -h, --help            show this help message and exit
  --suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}
                        Check one workload domain, such as language or vision
  --workload WORKLOAD   Check one workload id or canonical workload family
  --collection {starter,standard,research,all}
                        Check an explicit workload collection
  --profile {min,max,pro}
                        Contract depth: min=quick functional path,
                        max=complete quality evaluation for the selected
                        workload(s), pro=research variants and knobs. Defaults
                        to min.
  --variant VARIANT     Variant under a canonical workload
  --format {summary,json}
```

## mlperf init

```text
usage: mlperf init [-h] [--profile {min,max,pro}]
                   [--suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement} |
                   --workload WORKLOAD |
                   --collection {starter,standard,research,all}]
                   [--variant VARIANT] [--no-smoke] [--output-dir OUTPUT_DIR]

options:
  -h, --help            show this help message and exit
  --profile {min,max,pro}
                        Contract depth: min=quick functional path,
                        max=complete quality evaluation for the selected
                        workload(s), pro=research variants and knobs. Defaults
                        to min.
  --suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}
                        Prepare one workload domain, such as language or
                        vision
  --workload WORKLOAD   Prepare one workload id or canonical workload family
  --collection {starter,standard,research,all}
                        Prepare an explicit workload collection
  --variant VARIANT     Variant under a canonical workload
  --no-smoke
  --output-dir OUTPUT_DIR
                        Directory for init smoke-validation artifacts.
```

## mlperf list

```text
usage: mlperf list [-h]
                   [--suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}]
                   [--profile {min,max,pro}] [--workload WORKLOAD]
                   [--variant VARIANT]
                   [--public-status {score-bearing,performance-bearing,systems-only,experimental}]
                   [--format {summary,json}]
                   [{suites,profiles,workloads,variants,matrix}]

positional arguments:
  {suites,profiles,workloads,variants,matrix}
                        Discovery subject to list.

options:
  -h, --help            show this help message and exit
  --suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}
                        Filter by workload domain, such as language or vision
  --profile {min,max,pro}
  --workload WORKLOAD   Filter by workload id or canonical workload
  --variant VARIANT     Variant under a canonical workload
  --public-status {score-bearing,performance-bearing,systems-only,experimental}
  --format {summary,json}
```

## mlperf show

```text
usage: mlperf show [-h] [--variant VARIANT] workload

positional arguments:
  workload

options:
  -h, --help         show this help message and exit
  --variant VARIANT  Variant under a canonical workload
```

## mlperf info

```text
usage: mlperf info [-h]
                   (--suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement} |
                   --profile {min,max,pro} | --workload WORKLOAD |
                   --model MODEL | --dataset DATASET | --run RUN)
                   [--variant VARIANT]

options:
  -h, --help            show this help message and exit
  --suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}
                        Show one workload domain, such as language or vision
  --profile {min,max,pro}
  --workload WORKLOAD   Show one workload id or canonical workload family
  --model MODEL
  --dataset DATASET
  --run RUN
  --variant VARIANT
```

## mlperf fetch

```text
usage: mlperf fetch [-h]
                    [--suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement} |
                    --workload WORKLOAD |
                    --collection {starter,standard,research,all}]
                    [--profile {min,max,pro}] [--variant VARIANT] [--dry-run]

options:
  -h, --help            show this help message and exit
  --suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}
                        Select one workload domain, such as language or vision
  --workload WORKLOAD   Select one workload id or canonical workload family
  --collection {starter,standard,research,all}
                        Select an explicit workload collection
  --profile {min,max,pro}
                        Contract depth: min=quick functional path,
                        max=complete quality evaluation for the selected
                        workload(s), pro=research variants and knobs. Defaults
                        to min.
  --variant VARIANT     Variant under a canonical workload
  --dry-run
```

## mlperf run

```text
usage: mlperf run [-h]
                  [--suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement} |
                  --workload WORKLOAD |
                  --collection {starter,standard,research,all}]
                  [--profile {min,max,pro}] [--device {auto,cpu,cuda,mps}]
                  [--variant VARIANT] [--plan PLAN]
                  [--reference-plan REFERENCE_PLAN] [--output-dir OUTPUT_DIR]
                  [--open-report | --no-open-report] [--dry-run]
                  [--mode {training,inference}]
                  [--phase {full,prefill,decode}] [--power]

options:
  -h, --help            show this help message and exit
  --suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}
                        Select one workload domain, such as language or vision
  --workload WORKLOAD   Select one workload id or canonical workload family
  --collection {starter,standard,research,all}
                        Select an explicit workload collection
  --profile {min,max,pro}
                        Contract depth: min=quick functional path,
                        max=complete quality evaluation for the selected
                        workload(s), pro=research variants and knobs. Defaults
                        to min.
  --device {auto,cpu,cuda,mps}
                        Execution device. auto selects CUDA, then MPS, then
                        CPU. An explicit unavailable device fails before
                        execution.
  --variant VARIANT     Variant under a canonical workload
  --plan PLAN           Versioned pro experiment-plan YAML; replaces workload
                        selection
  --reference-plan REFERENCE_PLAN
                        Instructor-owned plan whose edit policy validates
                        --plan
  --output-dir OUTPUT_DIR
                        Directory for report artifacts.
  --open-report         Open the generated HTML dashboard.
  --no-open-report      Generate the HTML dashboard without opening a browser.
  --dry-run             Print selected workloads without running them
  --mode {training,inference}
                        Execution mode for a workload that defines training
                        and inference under one identity
  --phase {full,prefill,decode}
                        Inference phase; valid only with an inference-capable
                        single workload
  --power               Add estimated aggregate power and energy telemetry to
                        the run report
```

## mlperf verify

```text
usage: mlperf verify [-h] manifest

positional arguments:
  manifest

options:
  -h, --help  show this help message and exit
```

## mlperf report

```text
usage: mlperf report [-h] [--format {summary,json,csv,html}] [--output OUTPUT]
                     [--baseline BASELINE] [--open]
                     report

positional arguments:
  report                Path to a workload/aggregate report JSON, or a run
                        directory

options:
  -h, --help            show this help message and exit
  --format {summary,json,csv,html}
  --output OUTPUT       Output path for json/csv/html formats
  --baseline BASELINE   Compatible prior report to compare with the selected
                        result
  --open                Open generated HTML in the default browser
```

## mlperf package

```text
usage: mlperf package [-h] [--output OUTPUT] manifest

positional arguments:
  manifest

options:
  -h, --help           show this help message and exit
  --output, -o OUTPUT  Output .zip path
```

## mlperf audit

```text
usage: mlperf audit [-h]
                    [--suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}]
                    [--workload WORKLOAD] [--profile {min,max,pro}]
                    [--variant VARIANT]
                    [--status {score-bearing,performance-bearing,systems-only,experimental}]
                    [--policy {development,public}] [--format {summary,json}]

Maintainer command: audit registry metadata and public-result labels. This
does not run benchmarks.

options:
  -h, --help            show this help message and exit
  --suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}
                        Audit one workload domain, such as language or vision
  --workload WORKLOAD   Audit one workload id or canonical workload family
  --profile {min,max,pro}
  --variant VARIANT     Variant under a canonical workload
  --status {score-bearing,performance-bearing,systems-only,experimental}
  --policy {development,public}
                        Use public to fail on unresolved endorsement warnings.
  --format {summary,json}
```

## mlperf validate

```text
usage: mlperf validate [-h]
                       [--suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}]
                       [--output-dir OUTPUT_DIR] [--skip-doctor]
                       [--skip-grade] [--keep-going] [--dry-run]
                       [--open-report] [--device {auto,cpu,cuda,mps}]
                       [preset]

Run MLPerf EDU validation presets. This executes workloads and grades
artifacts.

positional arguments:
  preset                Validation preset: smoke=fast default/min,
                        coverage=all workloads/min, max=all workloads/max,
                        pro=research collection/pro, release=all
                        workloads/min+max and research collection/pro.

options:
  -h, --help            show this help message and exit
  --suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}
                        Restrict validation to one or more suites. Can be
                        passed multiple times.
  --output-dir OUTPUT_DIR
                        Root directory for validation artifacts.
  --skip-doctor         Skip the doctor preflight
  --skip-grade          Skip manifest grading after each run
  --keep-going          Continue after a failed validation item
  --dry-run             Print planned validation items without running them
  --open-report         Open the generated validation HTML summary
  --device {auto,cpu,cuda,mps}
                        Execution device. auto selects CUDA, then MPS, then
                        CPU. An explicit unavailable device fails before
                        execution.
```

## mlperf grade

```text
usage: mlperf grade [-h] [--assignment ASSIGNMENT] [--output OUTPUT]
                    [submissions_dir]

positional arguments:
  submissions_dir

options:
  -h, --help            show this help message and exit
  --assignment ASSIGNMENT
                        Versioned assignment YAML that fixes expected results
                        and configuration
  --output OUTPUT       Write grading summary JSON
```

## mlperf cache

```text
usage: mlperf cache [-h]
                    [--suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement} |
                    --workload WORKLOAD] [--profile {min,max,pro}]
                    [--variant VARIANT] [--format {summary,json}]
                    [{list,verify}]

positional arguments:
  {list,verify}

options:
  -h, --help            show this help message and exit
  --suite {language,vision,tiny,graph,timeseries,recommendation,reinforcement}
                        Inspect assets for one workload domain
  --workload WORKLOAD   Inspect assets for one workload id or canonical
                        workload family
  --profile {min,max,pro}
                        Contract depth: min=quick functional path,
                        max=complete quality evaluation for the selected
                        workload(s), pro=research variants and knobs. Defaults
                        to min.
  --variant VARIANT     Variant under a canonical workload
  --format {summary,json}
```