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
`index-verify`	Check an index's bytes against its recorded digests	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` or `trl`. 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.

To attribute an unsloth fine-tune, train it in your own script and point gradian attribute at the adapter, which needs nothing from unsloth to read. gradian train drives hf and trl only, for the reason in Limitations.

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 `repsim`
`--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 dataset, gradient spec, seed, damping and library versions the index was built from. Every number in a report is reproducible from this.

gradian index-verify#

Check that an index's stored bytes are the ones its manifest was written for.

gradian index-verify .gradian/index/<id>

Argument	Required	What it is
`path`	Yes	Index directory

index_id hashes the inputs of the computation, so two builds of one configuration that produced different numbers collide on the same id. The manifest also records a blake2b digest per stored block and one combined content_digest, which fingerprint the outputs. This command compares them against what is on disk, which is how you check that a cache hit is the exact index a recorded result was computed on.

Exit code	Meaning
`0`	Verified. Every block matches its recorded digest
`1`	Contents differ, or the path is not a complete index. Results computed on the recorded index are not reproducible from this one
`2`	Unverifiable. The index was written before digests existed. Rebuild with `--force` to get a verifiable one

gradian version#

Print the installed version.

gradian version