Command-line reference#
The command listing further down this page is rendered from the real Typer
application when the site is built, so it is the same text matmelt --help
prints on your machine. It cannot fall behind the code.
What surrounds it — the shared options, the exit-code conventions, and which commands write — is stated here once rather than repeated in nine help strings.
The commands at a glance#
Command |
Does |
Writes to your workspace |
|---|---|---|
|
Scaffold |
the config file |
|
Report backend health, per-stage dependencies, enumeration size |
no |
|
Execute the funnel until it drains |
yes — the state DB and item dirs |
|
Per-state tally, failures, in-flight jobs; |
no |
|
Live dashboard over a run in progress or finished |
no |
|
List finished materials, |
only with |
|
Reset |
yes — with |
|
Export CIFs of DFTB+ relaxed structures from the calculate stage |
writes the export directory |
|
Upgrade MatMelt in place, from the spec |
no (changes the install) |
Four commands open the state database read-only — status, monitor,
results and cif — which is enforced by SQLite’s query_only pragma rather
than by convention. Watching or exporting from a run cannot disturb it.
Exit codes#
The same three codes mean the same three things everywhere:
Code |
Meaning |
|---|---|
|
Success. |
|
The command refused, or found problems. |
|
Config error, or invalid flag usage. |
Two consequences are worth stating outright, because they are what people get wrong when scripting MatMelt:
Science failures are results, not process failures. A run in which
materials were screened out — even all of them — exits 0. The verdicts are
data; the run did its job. Likewise status exits 0 while listing failures.
Exit 1 means MatMelt could not do what you asked: unmet dependencies, an
unreachable backend, no run state yet, a refusal to overwrite, a failed export.
Exit 2 is always your file or your flags, never the science: unparseable
YAML, an unknown key, a broken cross-reference (each reported with its dotted
YAML path), or a usage conflict such as --only together with
pipeline.stop_after, an unknown --state, or an empty --materials
selection.
$ matmelt doctor --json > report.json # 0 = ready, 1 = problems found
$ matmelt run --yes # 0 even if every material fails screening
Full command listing#
matmelt#
Usage: matmelt [OPTIONS] COMMAND [ARGS]...
MatMelt -- melt elements into crystals. Run a multi-stage materials-discovery funnel
(compose → structure → screen → calculate → extract, where calculate is optional) on
your own machines, driven by a single YAML config.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --version Show the version and exit. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────────────╮
│ init Scaffold a starter config file and check the environment. │
│ run Run the pipeline to the configured stop-stage (--only STAGE for one stage; │
│ --materials for chosen materials + descendants). │
│ status Show per-stage progress and failures (--state STATE lists the material ids │
│ there — the picking list for 'run --materials'). │
│ monitor Watch the run live: a read-only dashboard of progress, backends, and │
│ failures (--once for a single snapshot). │
│ results List, inspect, and export finished materials from local storage. │
│ doctor Diagnose the environment, science dependencies, and backend reachability. │
│ retry Reset FAILED materials so a later run re-runs them (--stage/--materials to │
│ narrow; --dry-run to preview). │
│ cif Export CIF files of the DFTB+ relaxed structures that passed the calculate │
│ stage. │
│ update Update MatMelt in place, from the spec install.sh recorded. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
init#
Usage: matmelt init [OPTIONS]
Scaffold a starter config file and check the environment.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --config -c <str> Path to the YAML config file. [default: matmelt.yaml] │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
run#
Usage: matmelt run [OPTIONS]
Run the pipeline to the configured stop-stage (--only STAGE for one stage; --materials
for chosen materials + descendants).
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --config -c <str> Path to the YAML config file. │
│ [default: matmelt.yaml] │
│ --yes -y Assume consent for disclosed downloads. │
│ --max-passes <int> Stop after N passes (default: run until drained). │
│ --only <str> Run exactly one stage on demand (skips seeding │
│ unless it is compose; conflicts with │
│ pipeline.stop_after). │
│ --materials <str> Restrict the run to these comma-separated material │
│ ids and their descendants (browse ids with 'status │
│ --state'). │
│ --materials-file <str> Like --materials, from a file: one id per line, '#' │
│ comments and blank lines skipped. Combines with │
│ --materials. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
status#
Usage: matmelt status [OPTIONS]
Show per-stage progress and failures (--state STATE lists the material ids there — the
picking list for 'run --materials').
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --config -c <str> Path to the YAML config file. [default: matmelt.yaml] │
│ --json Emit the status as machine-readable JSON. │
│ --state <str> List the material ids currently at this state (e.g. │
│ 'screened') -- the picking list for 'run --materials'. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
monitor#
Usage: matmelt monitor [OPTIONS]
Watch the run live: a read-only dashboard of progress, backends, and failures (--once
for a single snapshot).
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --config -c <str> Path to the YAML config file. [default: matmelt.yaml] │
│ --interval <float> Seconds between dashboard refreshes. [default: 2.0] │
│ --once Print one snapshot and exit instead of watching live. │
│ --max-ticks <int> Stop the live view after N refreshes (default: watch │
│ until Ctrl-C). │
│ --track <str> Comma-separated material ids: show their detail │
│ instead of recent failures. │
│ --track-file <str> File of material ids to track, one per line ('#' │
│ comments allowed). │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
results#
Usage: matmelt results [OPTIONS]
List, inspect, and export finished materials from local storage.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --config -c <str> Path to the YAML config file. [default: matmelt.yaml] │
│ --json Emit the records as machine-readable JSON. │
│ --export <str> Write the records as a JSON array to PATH. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
doctor#
Usage: matmelt doctor [OPTIONS]
Diagnose the environment, science dependencies, and backend reachability.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --config -c <str> Path to the YAML config file. [default: matmelt.yaml] │
│ --json Emit the diagnosis as machine-readable JSON. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
retry#
Usage: matmelt retry [OPTIONS]
Reset FAILED materials so a later run re-runs them (--stage/--materials to narrow;
--dry-run to preview).
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --config -c <str> Path to the YAML config file. │
│ [default: matmelt.yaml] │
│ --stage <str> Only retry materials that failed at this stage. │
│ --materials <str> Only retry these comma-separated material ids. │
│ --materials-file <str> Like --materials, from a file: one id per line, '#' │
│ comments skipped. │
│ --dry-run Preview what would be reset, change nothing. │
│ --yes -y Skip the confirmation prompt. │
│ --json Emit the plan/result as JSON (applies only with │
│ --yes). │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
cif#
Usage: matmelt cif [OPTIONS]
Export CIF files of the DFTB+ relaxed structures that passed the calculate stage.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --config -c <str> Path to the YAML config file. │
│ [default: matmelt.yaml] │
│ --materials <str> Only export these comma-separated material ids. │
│ --materials-file <str> Like --materials, from a file: one id per line, '#' │
│ comments skipped. │
│ --out-dir <str> Where to write the CIFs (default: <work_dir>/cifs). │
│ --json Emit the export report as machine-readable JSON. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯
update#
Usage: matmelt update [OPTIONS]
Update MatMelt in place, from the spec install.sh recorded.
╭─ Options ────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────────────╯