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

## Usage

```bash
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](/docs/var/output-modes/)) |
| `--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

```bash
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

```bash
vary var src/
```

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

### Dry-run with rationale

```bash
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

```bash
vary var --json
```

JSON output following a versioned schema. See [output modes](/docs/var/output-modes/) for the schema reference.

### Compact output for CI

```bash
vary var --compact
```

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

```text
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

```bash
vary var --since-ref main
```

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

### Full pipeline with mutation

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

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

### Stateless run

```bash
vary var --no-state
```

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

### Fresh start

```bash
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](/docs/var/session-state/) for format and behaviour.