Skip to content

CLI Reference

The traincraft CLI is installed as a console script when you install the package.

traincraft --help

--help groups the commands by workflow — author & check configs (new, validate, plugins) → run the pipeline (run, stage, submit) → inspect runs (runs, status) → agents & services (serve, mcp) — and every command's own --help carries a usage example. The inspect commands take --json for scripting.

traincraft run

Run the complete workflow declared in a TOML config file.

traincraft run CONFIG [--force]

Arguments / options:

Argument / option Description
CONFIG Path to a .toml file (must exist and be readable)
--force, -f Recompute every stage, ignoring cached artifacts (a clean slate)

What it does:

  1. Loads and validates CONFIG via pydantic.
  2. Creates the workspace directory (runs/<name>/).
  3. Runs each active stage in order: geometry → sampling → selection → labeling → dataset → training → validation (only the sections you declared run).
  4. Prints a summary to stdout.

Slurm routing

If [orchestration].engine = "slurm", run instead renders and submits the stages as dependency-chained Slurm jobs (see submit).

Example:

traincraft run examples/07_co_on_cu_mc.toml

2026-05-30 10:00:01 [INFO] MD: T=500.0 steps=100 interval=20
2026-05-30 10:00:02 [INFO] dataset written: runs/07_co_on_cu_mc/dataset.extxyz (3 frames)
Done:
  workspace:    runs/07_co_on_cu_mc
  n_candidates: 6
  n_selected:   3
  dataset:      runs/07_co_on_cu_mc/dataset.extxyz

Smart caching — rerunning only redoes what changed

Each stage writes a sidecar <artifact>.key fingerprinting the inputs that produced it: its own config section (plus the run seed) and the upstream stage's key. On a rerun a stage is skipped only if its artifact exists and that fingerprint still matches.

So if you edit the config and rerun, the stages whose settings changed — and everything downstream of them — recompute automatically, while unrelated or expensive stages (e.g. DFT labeling) stay cached. Rerunning an unchanged config is a no-op that finishes in seconds.

Pass --force to ignore the fingerprints and recompute everything from scratch. (Per stage, the same escape hatch is traincraft stage NAME CONFIG --force.)

traincraft stage

Run a single pipeline stage standalone, reading the previous stage's artifact from the workspace and writing its own. This is what the HPC executor dispatches as separate jobs — and it's how you train on an existing dataset.

traincraft stage NAME CONFIG [--force]

Arguments / options:

Argument Description
NAME One of: geometry, sample, select, label, dataset, train, validate
CONFIG Path to a .toml file
--force Recompute even if the stage's artifact already exists

Example — train on a dataset you already built:

pixi run -e mace traincraft stage train my_run.toml

stage 'train': 42 frames

The train stage writes runs/<name>/model/<name>.model and a manifest.json. The validate stage writes runs/<name>/validation/quality_report.json — parity metrics + threshold checks for the trained model (see [validation]). See Tutorial 10 · Training.

traincraft submit

Render (and, unless --dry-run, submit) the workflow as dependency-chained Slurm jobs via Apptainer. Requires an [orchestration.slurm] section.

traincraft submit CONFIG [--dry-run]
Option Description
--dry-run Write the sbatch scripts but don't submit

The GPU stages (sample, train, validate) run in traincraft-mlip.sif with --nv; the DFT label stage injects the engine command. See Run on HPC.

traincraft runs

List every run under an output directory with its current status.

traincraft runs [OUTDIR] [--json]        # default: runs/

RUN                      STATUS     LAST STAGE   UPDATED                    ENGINE
cnt_water_600K           running    label        2026-07-07T15:58:11+00:00  slurm
validate_model           completed  validate     2026-07-07T16:11:02+00:00  local
seed_run                 failed     sample       2026-07-06T09:12:40+00:00  local

Backed by a SQLite index (<outdir>/index.db), refreshed lazily from each run's events.jsonl — only logs that changed since the last look are re-read, so this stays fast with thousands of runs. The index is a disposable cache: deleting index.db is always safe (it is rebuilt on the next call), and compute jobs never write to it — on HPC they only append to their own run's event log, which is why the whole scheme is safe on Lustre/NFS.

traincraft status

Per-stage status of a single run, read from its events.jsonl.

traincraft status RUN_DIR [--json]       # e.g. traincraft status runs/cnt_water_600K

run: cnt_water_600K  [running]  engine=slurm
  geometry   done  1 frames  0.4s
  sample     done  2000 frames  841.2s
  select     done  400 frames  12.1s
  label      running  231 done / 4 failed so far
  validate   pending

States per stage: pending (not reached), running, done, cached (skipped — artifact up to date), failed (with the error message). While the label stage runs, live frame counts are read from labeled_dft/receipts.jsonl. Every run directory carries its own state — no daemon or database is required to ask where a run is, from any login node.

traincraft serve

Serve the HTTP API over a runs directory (needs pixi install -e service).

traincraft serve [OUTDIR] [--host 127.0.0.1] [--port 8137]

Endpoints: runs list/status/events, quality reports, stage manifests, config validation, pipeline submission — OpenAPI docs at /docs. Localhost tool with no auth; see Serve Runs to Agents & UIs.

traincraft mcp

Run the MCP server on stdio — the same operations as agent tools (list_runs, run_status, quality_report, stage_manifest, validate_config, submit_run).

claude mcp add traincraft -- pixi run -e service traincraft mcp /abs/path/to/runs

See Serve Runs to Agents & UIs.

traincraft validate

Validate a config file without running anything.

traincraft validate CONFIG

Arguments:

Argument Description
CONFIG Path to a .toml file

What it does: loads and validates the config, prints which stages are active, and exits. Use this to catch typos and logical errors before a long run.

Example:

traincraft validate examples/07_co_on_cu_mc.toml

OK: config is valid
  run:    07_co_on_cu_mc
  stages: geometry, calculator, sampling, selection, dataset

If the config is invalid:

traincraft validate broken.toml

Error: 1 validation error for TrainCraftConfig
geometry -> builder -> type
  Input should be 'nanotube', 'molecule', ... [type=literal_error, ...]

traincraft new

Write a starter config file to a given path.

traincraft new PATH

Arguments:

Argument Description
PATH Where to write the starter .toml file

What it does: generates a commented starter config covering all major sections and writes it to PATH. Refuses to overwrite an existing file.

Example:

traincraft new my_run.toml
cat my_run.toml

traincraft plugins

List all registered plugins grouped by kind.

traincraft plugins

Output:

source:    file, materials_project, optimade, pubchem, scratch, smiles, url
builder:   crystal, intercalation, layered, liquid, molecule, nanotube, slab, surface_adsorbate, surface_packing
transform: constraints, perturb, rotate, set_pbc, strain, supercell, vacuum
calculator: emt, fhi_aims, mace, qe, tblite, xtb
sampler:   md, monte_carlo, rattle
selector:  dedup, diversity, physicality
trainer:   mace

Plugin availability depends on your environment

smiles and surface_packing appear only when RDKit/Packmol are installed. mace and xtb appear only when their respective packages are installed.