CLI reference

Every gradian command and every flag, with what it does and when you need it.

gradian [COMMAND] [OPTIONS]

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

Most commands accept --config and let individual flags override it. See Configuration.

gradian doctor#

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

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.

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.

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.

gradian checks

No options. Prints the category, id and one-line description of all 41. See 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.

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.

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.

gradian attribute#

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

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.

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.

gradian version