---
description: A short checklist that proves your MatMelt install is sound before you rely on it.
---

# Verify your install

Nine checks. Each is one command with an unambiguous answer, and each tells you
something different. If they all pass, the tool, your science stack and your
workspace are sound.

## 1. The command exists and reports its version

```console
$ matmelt --version
matmelt 0.2.0
```

If this fails, the launcher is not on your `PATH` — see {doc}`installation`.

## 2. Every command is present

```console
$ matmelt --help
```

You should see `init`, `doctor`, `run`, `status`, `retry`, `results`, `monitor`,
`cif` and `update`.

## 3. The scaffolded config is valid as written

```console
$ mkdir /tmp/matmelt-check && cd /tmp/matmelt-check
$ matmelt init
```

`init` refuses to overwrite an existing config, so run it in an empty directory.
It scaffolds and then immediately diagnoses; a scaffold that could not be loaded
would fail here.

## 4. Backends are reachable

In the `doctor` output, the **Backend reachability** table must show `healthy`
for every backend. For the scaffolded `local` backend this means its work
directory is writable. A remote backend being unreachable is reported here, not
discovered halfway through a run.

## 5. Every stage's dependencies are importable

The **Stage readiness** table must show `ok` for each stage you intend to run.
`MISSING` prints the exact install command underneath. Remember that the probe
runs in *that stage's* interpreter, on the machine that stage will use.

## 6. `doctor` exits 0

```console
$ matmelt doctor
$ echo $?
0
```

Exit code 0 means every check passed. Exit 1 means at least one problem was
reported; exit 2 means the config itself could not be read.

## 7. The enumeration is the size you expect

`doctor` prints the seed enumeration before any work is possible:

```text
Seed enumeration: 2 element(s) -> 3 combination(s) (size 1: 2, size 2: 1).
```

This is the blast radius of your element set. It grows combinatorially — check
it before starting a run you did not intend, especially after widening
`elements` or `combination_sizes`.

## 8. A real job runs end to end

The strongest check is a complete run, because it exercises the whole path:
job submission, the state database, output collection and the stage contracts.
{doc}`first-run` is that check — if it produced a `record.json`, everything
below the CLI works.

## 9. Read-only commands leave the workspace untouched

```console
$ matmelt status
$ matmelt results
$ matmelt monitor --once
```

All three open the state database read-only and cannot modify a run. `monitor
--once` renders a single dashboard frame and exits, which is a safe way to
confirm it works without holding a live view open.

## If something fails

| Symptom | Where to look |
|---|---|
| `matmelt: command not found` | {doc}`installation` — the `PATH` note |
| A stage says `MISSING` | {doc}`dependencies` — run the printed command |
| A backend is unhealthy | {doc}`../how-to/doctor` |
| The run starts but materials go to `FAILED` | {doc}`../how-to/diagnose-a-failure` |
| A model download is refused or fails | {doc}`dependencies` — the MACE model section |
