Source: https://gradian.dev/docs/cli

# CLI reference

```
gradian [COMMAND] [OPTIONS]
```

| Command | What it does | Needs a GPU |
|---|---|---|
| [`doctor`](#gradian-doctor) | Environment, dependency window, devices, backends | No |
| [`init-config`](#gradian-init-config) | Write a starter `gradian.yaml` | No |
| [`diagnose`](#gradian-diagnose) | Dataset, config and dynamics audit | No |
| [`checks`](#gradian-checks) | List all 41 diagnostic checks | No |
| [`train`](#gradian-train) | Optional convenience, launch a LoRA fine-tune | Yes |
| [`index`](#gradian-index) | Build the per-example gradient index | Yes, in practice |
| [`attribute`](#gradian-attribute) | Score training data against a capability, write a report | Yes, in practice |
| [`show-index`](#gradian-show-index) | Print an index manifest for provenance | No |
| [`version`](#gradian-version) | Print the installed version | No |

Most commands accept `--config` and let individual flags override it. See
[Configuration](/docs/configuration).

## gradian doctor

Check the environment: packages, versions, devices, determinism, backends.

```bash
gradian doctor
```

No options. Run it after installing, and again whenever behavior surprises you. It reports installed
versions against the supported window, visible devices, determinism settings, and which training
backends are available along with the reason any are not.

## gradian init-config

Write a starter config file.

```bash
gradian init-config --base-model meta-llama/Llama-3.2-1B-Instruct
```

| Option | Short | Default | What it does |
|---|---|---|---|
| `--out` | `-o` | `gradian.yaml` | Where to write the config |
| `--base-model` | `-m` | empty | Pre-fill the base model id |

## gradian diagnose

Diagnose a dataset, config and run without any attribution. No GPU required.

```bash
gradian diagnose --dataset train.jsonl --run runs/my-finetune --base-model meta-llama/Llama-3.2-1B
```

| Option | Short | What it does |
|---|---|---|
| `--config` | `-c` | YAML config file |
| `--dataset` | `-d` | Training dataset, `.jsonl` or `.json` |
| `--eval-dataset` | | Eval dataset, which enables the contamination checks |
| `--run` | `-r` | Run directory holding trainer logs and the adapter |
| `--base-model` | `-m` | Base model id, used for the tokenizer |
| `--max-seq-length` | | Sequence length used in training, for the truncation checks |
| `--out` | `-o` | Write the report to this directory |

`--base-model` is used only to load the tokenizer, so the truncation and EOS checks can count real
tokens. Without it those checks cannot run. Passing `--run` is what enables the config and dynamics
checks, which is two thirds of the 41.

## gradian checks

List every registered diagnostic check.

```bash
gradian checks
```

No options. Prints the category, id and one-line description of all 41. See
[Diagnostics](/docs/diagnostics) for the same list with context.

## gradian train

Fine-tune a LoRA adapter. This is an optional convenience path, not part of the main flow. See
[The workflow](/docs/workflow#when-you-would-use-gradian-train).

```bash
gradian train --config gradian.yaml --backend hf --out runs/my-finetune
```

| Option | Short | Required | What it does |
|---|---|---|---|
| `--config` | `-c` | Yes | YAML config file |
| `--backend` | `-b` | | `hf`, `trl` or `unsloth`. Defaults to `hf` |
| `--dataset` | `-d` | | Training dataset, overriding the config |
| `--out` | `-o` | | Output directory for the run |

`--config` is the one required flag here, unlike the other commands. On success it writes the adapter
plus a `gradian_run.json` run artifact that the other commands can read.

Note that `backend: trl` is not accepted in a YAML config file, only as `--backend trl` on the command
line.

## gradian index

Build the per-example gradient index. Expensive, cached and content-addressed.

```bash
gradian index --base-model meta-llama/Llama-3.2-1B-Instruct \
              --adapter runs/my-finetune/adapter \
              --dataset train.jsonl
```

| Option | Short | What it does |
|---|---|---|
| `--config` | `-c` | YAML config file |
| `--dataset` | `-d` | Training dataset |
| `--base-model` | `-m` | Base model id or path. Required |
| `--adapter` | `-a` | LoRA adapter directory |
| `--force` | | Rebuild even if a cached index exists |

`--base-model` and `--dataset` are required, whether from flags or the config. `gradian attribute`
builds the index for you, so run this separately only when you want the cost up front or want to
build once and query many times.

The gradient settings that control cost and size, such as batch size, sequence length, module filter
and projection, live in the config under `grads`. They are not command line flags. See
[Configuration](/docs/configuration#grads).

## gradian attribute

Attribute a capability change to training data, and write a merged report.

```bash
gradian attribute \
  --base-model meta-llama/Llama-3.2-1B-Instruct \
  --adapter runs/my-finetune/adapter \
  --dataset train.jsonl \
  --eval-dataset capability_eval.jsonl \
  --capability json_formatting \
  --out reports/
```

| Option | Short | Default | What it does |
|---|---|---|---|
| `--config` | `-c` | | YAML config file |
| `--dataset` | `-d` | | Training dataset |
| `--eval-dataset` | `-e` | | Items describing the capability, with the answers you wanted |
| `--base-model` | `-m` | | Base model id or path |
| `--adapter` | `-a` | | LoRA adapter directory. Required |
| `--run` | `-r` | | Run directory, which merges the audit into the report |
| `--capability` | | `capability` | Name for the capability, used in the report |
| `--engine` | | `datainf` | `datainf`, `graddot` or `tracin` |
| `--cross-check` | | `graddot` | Second engine for rank agreement, or `none` |
| `--out` | `-o` | | Write the report to this directory |
| `--force` | | | Rebuild the index |

Without `--adapter` this exits with code 2, because attribution needs adapter parameters to
differentiate with respect to. Without `--eval-dataset` it falls back to a degraded mode and flags
that in the report.

Pass `--run` to get one report containing both the attribution verdict and the audit findings, which
is the point of the tool. Without it you get attribution alone.

## gradian show-index

Print an index manifest for provenance.

```bash
gradian show-index .gradian/index/<id>
```

| Argument | Required | What it is |
|---|---|---|
| `path` | Yes | Index directory |

Prints the manifest as JSON: the checkpoint, dataset, gradient spec, seed, damping and library
versions the index was built from. Every number in a report is reproducible from this.

## gradian version

Print the installed version.

```bash
gradian version
```