docs/cli.md

CLI reference

The mindxtrain Typer app: 9 verbs (8 top-level + a dataset subgroup). Every verb that consumes a YAML config validates it against the 10-section schema before doing anything else.

mindxtrain [--version] <verb> [options]

All verbs dispatch into real Python in the canonical mindxtrain.* modules. Verbs that require optional dependencies surface a clean run uv sync --extra `` hint and exit 3.

Global options

Flag	Purpose
--version	Print the version and exit.
--help	Show help for the top-level command.

init — scaffold a YAML

Render a built-in recipe to disk.

mindxtrain init [--template <name>] [--out <path>] [--list]

Option	Default	Description
--template, -t	qwen3_8b_sft_lora	recipe name; see --list
--out, -o	run.yaml	output path
--list	flag	print every built-in recipe and exit

Available recipes (12 total):

instella_3b_lora        qwen3_30b_a3b_lora      qwen3_32b_dpo
qwen3_32b_full_fsdp     qwen3_32b_grpo          qwen3_32b_orpo
qwen3_6_27b_lora        qwen3_6_35b_a3b_lora    qwen3_8b_cpt
qwen3_8b_sft_full       qwen3_8b_sft_lora       qwen3_vl_8b_sft

$ uv run mindxtrain init --template qwen3_8b_sft_lora --out run.yaml
wrote run.yaml (2785 bytes, recipe='qwen3_8b_sft_lora')

bench — run the 60-second AOT autotune probe

The differentiator. See autotune.md for probe taxonomy.

mindxtrain bench [--gpu N] [--out <path>] [--dry-run]

Option	Default	Description
--gpu	0	HIP/ROCm device index
--out, -o	autotune_plan.json	output path
--dry-run	flag	skip GPU probes; emit a synthetic reference plan (CPU-safe)

--dry-run is the CPU-only path used in tests and CI. A real mindxtrain bench --gpu 0 requires torch (--extra ml) and an MI300X with ROCm 7.2.1; if torch is unavailable, the attention probe gracefully falls back to the canonical ck default.

train — dispatch a training run

mindxtrain train <config.yaml> [--plan <plan.json>] [--out <run-dir>]

Option	Default	Description
--plan	(uses dry-run plan)	autotune plan JSON from mindxtrain bench
--out, -o	./out/runs	output root for <run_id>/ directory

Loads the YAML, dispatches to train.backend (axolotl, unsloth, torchtune, primus). The Axolotl path subprocess-wraps accelerate launch -m axolotl.cli.train. Plan-derived env vars (PYTORCH_ROCM_ARCH=gfx942, HSA_NO_SCRATCH_RECLAIM=1, etc.) are injected before launch.

Requires --extra ml plus the chosen backend on PATH.

Exits 3 with a clean install hint if accelerate (or the backend) is missing.

dataset prep — run the dataset pipeline

mindxtrain dataset prep <config.yaml> [--out <dir>]

Streams the HF dataset (datasets), runs heuristic + optional MinHash/SemDeDup filters, tokenizes (AutoTokenizer), packs to data.seq_len, emits sharded .tar files. Pin the resulting tars via mindxtrain.storage.lighthouse or mindxtrain.storage.ipfs.

Requires --extra ml (datasets, transformers).

eval — run lm-evaluation-harness

mindxtrain eval <config.yaml> [--checkpoint <path>]

Option	Default	Description
--checkpoint, -c	./out/runs/<run_name>/checkpoint	path to the checkpoint dir

Subprocess-wraps lm_eval --model hf --tasks <comma-sep>. Tasks come from cfg.eval.harness.tasks. Output JSON written under <checkpoint>/eval/lm_eval.json. Summary printed via mindxtrain.eval.harness.parse_summary.

Requires --extra eval.

quantize — Quark FP8 / MXFP4

mindxtrain quantize <config.yaml> [--checkpoint <path>]

Wraps python -m amd_quark.quantize with --scheme fp8_e4m3 (default) or --scheme mxfp4 (CDNA 4 / MI350X+). Output is a quantized/ directory next to the checkpoint, vLLM-loadable.

Requires the amd-quark package — typically only available inside the rocm/primus:v26.2 container or per Quark docs.

serve — print the vLLM-ROCm launch command

mindxtrain serve <config.yaml> [--checkpoint <path>]

Builds the vllm serve argv from cfg.serve and prints it. We deliberately don't exec — the user pipes it into their own orchestrator (or ops/compose/compose_dev.yaml).

The chat-template parsers map per serve.reasoning_parser (qwen3 for Qwen3, deepseek_r1 for DeepSeek-style) and serve.tool_call_parser (hermes, qwen3_coder).

publish — push to HF + Lighthouse + register

mindxtrain publish <config.yaml> --manifest <manifest.json> [--skip-hf] [--skip-pin]

1. mindxtrain.storage.hf_hub.publish_to_hf — uploads the checkpoint dir to HuggingFace Hub (uses HF_TOKEN). --skip-hf to bypass.
2. mindxtrain.storage.lighthouse.publish_to_lighthouse — pins to Lighthouse via direct httpx POST (uses LIGHTHOUSE_API_KEY). Falls back to a stub cid://stub-... derived from the checkpoint's BLAKE3 if the key is unset. --skip-pin to bypass entirely.
3. mindxtrain.deploy.api_client.register_with_mindx — POSTs the run-id / HF URL / CID to MINDXTRAIN_API_BASE_URL/v1/agents. Skipped gracefully if the endpoint isn't reachable.
4. The manifest JSON file is updated in-place with the resulting hf_repo_id and lighthouse_cid fields.

receipt — verify a provenance manifest

mindxtrain receipt <manifest.json> [--config <run.yaml>]

Loads the manifest and prints the run-id + BLAKE3 fields. With --config, also re-hashes the on-disk artifacts (config_yaml, dataset, checkpoint, eval_json) and emits a per-field pass/fail dict — exits 0 if every hash verifies, 2 if any drift is detected.

$ uv run mindxtrain receipt out/runs/<run_id>/manifest.json --config run.yaml
{
  "config_yaml": true,
  "dataset": true,
  "checkpoint": true,
  "eval_json": true
}

Exit-code summary

Code	Meaning
0	Success.
1	Bad input — missing file, hash mismatch, schema error.
2	Verify failed — at least one BLAKE3 field doesn't match disk.
3	Optional dep missing — install with uv sync --extra <group>.

Where the verbs live

Verb	Module
init	mindxtrain.cli.main.init + mindxtrain.config.loader.render_recipe
bench	mindxtrain.cli.main.bench + mindxtrain.autotune.benchmark.run_autotune
train	mindxtrain.cli.main.train + mindxtrain.train.dispatch.dispatch_training
dataset prep	mindxtrain.cli.main.dataset_prep + mindxtrain.data.{curate,filter,tokenize,pack}
eval	mindxtrain.cli.main.eval_ + mindxtrain.eval.harness.run_lm_eval
quantize	mindxtrain.cli.main.quantize + mindxtrain.deploy.quark.quark_fp8
serve	mindxtrain.cli.main.serve + mindxtrain.deploy.vllm_launcher.build_vllm_command
publish	mindxtrain.cli.main.publish + mindxtrain.storage.{hf_hub,lighthouse} + mindxtrain.deploy.api_client
receipt	mindxtrain.cli.main.receipt + mindxtrain.provenance.verify.verify_receipt