CLI reference

Run vary var to check what validation work remains and drive the next iteration.

Usage

vary var [options] [paths...]

Positional arguments are files or directories to scope the change set. Default: . (current directory).

Options

Flag	Description
--json	Output as JSON (schema version 1.0.0)
--compact	Compact single-line output for scripting
--reset	Clear saved session state and start fresh
--no-state	Run without reading or writing session state
--dry-run	Preview planned actions without executing them
--explain	Show rationale for each planned action (use with --dry-run)
--since-ref <ref>	Only consider changes since a git ref (e.g., main, HEAD~3)
--max-cost <level>	Cap iteration cost: low, medium (default), high
--include-mutation	Include mutation testing in the iteration
--include-review-packet	Include review-packet generation in the iteration

Examples

Basic status

vary var

Shows the current pipeline state: completed stages, blockers, and what to do next. On first run, starts with discovery.

Scoped to a directory

vary var src/

Only considers changes within src/. Useful in monorepos or when you want to focus on one area.

Dry-run with rationale

vary var --dry-run --explain

Shows what stages would run and why, without executing anything. Preview cost before committing to a full run.

Machine-readable output

vary var --json

JSON output following a versioned schema. See output modes for the schema reference.

Compact output for CI

vary var --compact

Produces terse multi-line output parseable with simple text tools:

stage=check status=blocked blockers=2
changes=+3 ~5 -1 src:4 test:3 cfg:2
check: errors=2 warnings=1
next: fix 2 check error(s)

Changes since a branch point

vary var --since-ref main

Only considers files that differ from main. The typical feature-branch workflow.

Full pipeline with mutation

vary var --include-mutation --max-cost high

Full pipeline including mutation testing, with a high cost budget.

Stateless run

vary var --no-state

Runs without reading or writing session state. Every invocation starts fresh. Good for one-off CI checks.

Fresh start

vary var --reset

Clears the saved session and starts from discovery. Re-validates everything from scratch.

Exit codes

Code	Meaning
0	Pipeline completed (COMPLETE or ADVISORY)
1	Pipeline blocked (BLOCKED) or partially complete (PARTIAL)
2	Usage error (bad flags, path not found)

Session file

VAR persists state to .vary-var-session.json in the project root. See session state for format and behaviour.