The `vary` command is a single binary that covers the full development lifecycle: running code, type-checking, testing, formatting, mutation testing, and building.

```bash
vary <command> [options]
```

## Running code

### `vary run`

Compile and run a Vary file.

```bash
vary run hello.vary
vary run server.vary --verbose
vary run app.vary -- arg1 arg2
```

| Flag | Description |
|------|-------------|
| `-v, --verbose` | Verbose output |
| `--no-cache` | Disable artifact caching |
| `-cp, --classpath` | Additional classpath entries (separated by `:`) |
| `-t, --variant` | Build variant: `normal`, `debug`, `coverage` |
| `-W, --warnings` | Warning mode: `all` (default), `none`, `error` |
| `--profile-phases` | Show compiler phase timings. Optional value: `human` (default) or `json` |

Arguments after `--` are passed to the Vary program as `sys.argv`.

### `vary repl`

Start an interactive read-eval-print loop.

```bash
vary repl
```

### `vary dev`

Hot-reload development mode. Watches source files for changes and restarts automatically.

```bash
vary dev
vary dev app.vary
vary dev --port 8080
```

| Flag | Description |
|------|-------------|
| `-v, --verbose` | Verbose output |
| `-p, --port` | Port for Quarkus dev mode |
| `-d, --debug` | Enable debug mode |
| `-s, --suspend` | Suspend on start (wait for debugger) |

## Code quality

### `vary check`

Type-check and lint a file or directory without running it. Reports type errors, undefined variables, import issues, and rule-based diagnostics. When given a directory, checks all `.vary` files and prints a summary.

The check engine includes a rule-based diagnostic system with auto-fix support. Rules are organized by category (idioms, contracts, mutation, testing, etc.) and identified by stable IDs (e.g., `VCI001` for idiom rules).

```bash
vary check src/main.vary
vary check src/
vary check src/ --fix              # apply safe auto-fixes
vary check src/ --rule VCI001      # run only a specific rule
vary check src/ --category idioms  # run only idiom rules
vary check src/ --json             # machine-readable output
vary check src/ --explain VCI001   # explain a specific rule
vary check src/ --plan             # show ordered repair plan
vary check src/ --profile ci       # CI mode: JSON + warnings as errors
```

| Flag | Description |
|------|-------------|
| `-v, --verbose` | Verbose output |
| `-s, --summary` | One line per file, no details |
| `-W, --warnings` | Warning mode: `all` (default), `none`, `error` |
| `--fix, --fix-safe` | Apply safe auto-fixes in place |
| `--category` | Filter rules by category (repeatable) |
| `--rule` | Filter rules by ID (repeatable) |
| `--json` | Machine-readable JSON output |
| `--explain [RULE]` | Explain a rule by ID or name; omit to list all |
| `--profile` | Check profile: `ci` (JSON + warnings error) or `local` |
| `--plan` | Output an ordered repair plan |
| `--group` | Group output by `priority` (default) or `file` |

See [Check rules](/docs/check/) for the full list of shipped rules and what each one detects.

### `vary fmt`

Format source files. Zero configuration, one style.

```bash
vary fmt src/
vary fmt --check src/
vary fmt --diff src/app.vary
```

| Flag | Description |
|------|-------------|
| `--check` | Check formatting without modifying files (exits non-zero if changes needed) |
| `--diff` | Show diff of formatting changes |

### `vary loc`

Count lines of Vary code in a file or directory.

```bash
vary loc
vary loc src/
```

## Testing

### `vary test`

Run tests. Discovers `test "name" { }` blocks in `.vary` files.

```bash
vary test tests/
vary test tests/test_math.vary
vary test tests/ --filter math
vary test tests/ -j 4
```

| Flag | Description |
|------|-------------|
| `-f, --filter` | Filter test files by name pattern |
| `-j, --jobs` | Number of parallel test files (default: 1) |
| `--only` | Run a single test by identity (`module.path::test_name`) |
| `-v, --verbose` | Verbose output |
| `--coverage` | Enable code coverage tracking |
| `--coverage-report` | Coverage format: `text`, `html`, `json` |
| `--coverage-dir` | Directory for coverage reports (default: `coverage`) |
| `--min-line-coverage` | Minimum line coverage percentage (0-100) |
| `--min-branch-coverage` | Minimum branch coverage percentage (0-100) |
| `--json` | Output results as JSON |

### `vary mutate`

Mutation testing. Applies small changes to your code and checks whether your tests catch them.

```bash
vary mutate src/math.vary -t tests/test_math.vary
vary mutate src/ --quick
vary mutate src/math.vary -t tests/test_math.vary --certify
```

| Flag | Description |
|------|-------------|
| `-t, --tests` | Test file or directory to run against mutants |
| `--operators` | AST mutation operators (comma-separated) |
| `--bc-operators` | Bytecode mutation operators (comma-separated) |
| `--level` | Mutation level: `ast`, `bytecode`, or `both` |
| `--quick` | Quick mode: limited operators, max 20 mutants |
| `-j, --parallel` | Number of parallel workers (default: available cores) |
| `--budget` | Time budget (e.g., `30s`, `5m`) |
| `--timeout` | Per-mutant timeout in milliseconds (default: 5000) |
| `-v, --verbose` | Verbose output |
| `-i, --incremental` | Reuse cached results from previous runs |
| `--cache-file` | Cache file location |
| `--all` | Mutate all methods (disable changed-only mode) |
| `--no-dedup` | Disable mutant deduplication |
| `--certify` | Generate a mutation testing certificate |
| `--trend` | Show score trend compared to previous run |
| `--replay` | Replay a single mutation by its stable ID |
| `--promote` | Promote run artifacts to `.vary/runs/` |
| `--report` | Report format: `text`, `html`, `json` |
| `--report-dir` | Directory for reports (default: `mutation-reports`) |
| `--why` | Explain why a specific mutant survived |
| `--observe` | Enable runtime observability tracking |
| `--differential` | Enable differential trace detection |
| `--top` | Number of survivor groups to display (default: 20) |
| `--group` | Group survivors by: `function`, `file`, or `cause` |
| `--expand` | Expand a survivor group |
| `--emit` | Emit format: `agent-bundle` |
| `--quarantine` | Quarantine a surviving mutant by ID |
| `--quarantine-reason` | Reason for quarantining |
| `--unquarantine` | Remove a mutant from quarantine by ID |
| `--list-quarantined` | List all quarantined mutants |
| `--strict-selection` | Test selection mode: `evidence` (default) or `reference` |
| `--reachability` | Record per-test method reachability during baseline |
| `--warm-workers` | Reuse long-lived workers: `on` (default) or `off` |
| `--fresh-workers` | Alias for `--warm-workers=off` |
| `--backend` | Bytecode backend: `fresh-loader` (default), `hot-swap`, or `redefine` (in-process class redefinition via `java.lang.instrument`) |
| `--relevance-graph-path` | Override the persisted relevance graph location |
| `--explain` | Include selection and scheduling explanation in the report |
| `--incremental-infer` | Reuse prior mutant outcomes when source, tests, and operators are unchanged; labels each mutant `inferred` or `executed` ([Incremental inference](/docs/mutation/incremental-inference/)) |
| `--fast-mode` | Heuristic narrowing of the coverage-guided test filter, validated each run with automatic fallback when miss rate exceeds threshold ([Fast mode](/docs/mutation/fast-mode/)) |
| `--fast-mode-narrow-factor` | Fraction of conservative test filter kept under fast mode (`0.0..1.0`, default `0.5`) |
| `--fast-mode-sample-size` | Mutants re-run with the broader filter to measure miss rate (default `10`) |
| `--fast-mode-miss-threshold` | Miss rate above which fast mode falls back automatically (`0.0..1.0`, default `0.10`) |

See [Strict mode](/docs/mutation/strict-mode/) for how these flags interact.

### `vary mutate-parity`

Compare the reference `fresh-loader` backend against a candidate bytecode backend (`redefine` or `hot-swap`) and fail when any mutant's kill/survive classification differs. The parity gate is the continuous defence that keeps a performance backend safe to ship. See [Parity gate](/docs/mutation/parity-gate/).

```bash
vary mutate-parity src/utils.vary -t tests/test_utils.vary
vary mutate-parity src/utils.vary --candidate hot-swap
vary mutate-parity programs/frugal --corpus
```

| Flag | Description |
|------|-------------|
| `-t, --tests` | Test file or directory (single-file mode) |
| `--candidate` | Candidate backend: `redefine` (default) or `hot-swap` |
| `--corpus` | Pinned-corpus mode: walk a project directory |
| `--json` | Echo `parity-report.json` to stdout as well as writing the file |

A non-empty `mismatches` array exits non-zero. `mutation-reports/parity-report.json` is always written.

### `vary benchmark`

Strict-mode parity benchmark. Runs mutation testing across multiple modes and fails if any mode classifies a mutant differently from the reference baseline.

```bash
vary benchmark                               # all modes against built-in fixtures
vary benchmark --fixture-dir tests/mutation/ # custom fixtures
vary benchmark --mode reference              # single mode
vary benchmark --mode evidence+warm          # evidence-based + warm workers
vary benchmark --runs 3                      # multiple iterations
vary benchmark --output-dir ./results        # custom output location
```

| Flag | Description |
|------|-------------|
| `--mode <name>` | Mode to run: `reference`, `evidence`, `evidence+warm`, `fresh-loader`, `hotswap`, `backend-parity`, or `all` (default) |
| `--fixture-dir <path>` | Fixture directory (default: built-in fixtures) |
| `--output-dir <path>` | Where to write the benchmark artifact (default: `.vary-logs/`) |
| `--runs <n>` | Number of iterations per mode (default: 1) |

The benchmark fails on any cross-mode classification mismatch, empty `killedBy` for a killed mutant, or flaky classification across identical runs. See [Benchmark](/docs/mutation/benchmark/) for the parity model and metrics.

### `vary validate`

Run validation stages across a project: static analysis, tests, mutation testing.

```bash
vary validate src/
vary validate src/ --profile ci
vary validate src/ --only mutation --budget 2m
vary validate src/ --only contracts
```

| Flag | Description |
|------|-------------|
| `-p, --profile` | Validation profile: `fast` (default), `ci`, `mutation`, `mutation-strict`, `oracle` |
| `--only` | Run a single stage: `analyze`, `static`, `tests`, `mutation`, `oracle`, `contracts` |
| `--budget` | Time budget for mutation stage |
| `--require-complete` | Fail if budget ran out before all mutants were tested |
| `--show-all-survivors` | Show all survivor groups (default: top 10) |
| `-v, --verbose` | Verbose output |

The `contracts` stage runs tests and reports any contract violations (`in`/`post`/`out`/`old`) in a structured format showing the violation kind, function name, file location, and failing expression. See [Contracts](/docs/contracts/) for details.

## Building

### `vary build`

Compile a Vary file to a runnable JAR, or build a Quarkus project.

```bash
vary build app.vary -o app.jar
vary build app.vary --name myapp
```

| Flag | Description |
|------|-------------|
| `-o, --output` | Output JAR file path |
| `--name` | Create a CLI alias for the built JAR (installed to `~/.vary/bin/`) |
| `--force-alias` | Overwrite an existing alias |
| `-n, --native` | Build native executable (Quarkus projects only, requires GraalVM) |
| `--skip-tests` | Skip running tests during build |
| `-v, --verbose` | Verbose output |
| `-W, --warnings` | Warning mode: `all` (default), `none`, `error` |

## Project management

### `vary new`

Create a new Vary project with standard layout (`src/`, `test/`, `vary.toml`).

```bash
vary new my-app
vary new my-app --force
vary new my-app --devcontainer
vary new my-app --template serious
```

| Flag | Description |
|------|-------------|
| `-f, --force` | Overwrite existing directory |
| `--devcontainer` | Include `.devcontainer/` config for VS Code Dev Containers |
| `-t, --template` | Project template: `minimal` (default) or `serious` |

The `serious` template scaffolds a production-ready project with `src/core/`, `tests/`, `vary.toml` with validation profiles (local, ci, nightly), and a `.github/workflows/vary-ci.yml` GitHub Actions workflow.

### `vary init`

Initialize a `vary.toml` configuration file in the current directory.

```bash
vary init
vary init --name my-project
```

| Flag | Description |
|------|-------------|
| `-n, --name` | Project name (default: `my-project`) |
| `-f, --force` | Overwrite existing `vary.toml` |

### `vary config`

Print the resolved project configuration.

```bash
vary config
vary config --verbose
```

| Flag | Description |
|------|-------------|
| `-v, --verbose` | Show all config details |

### `vary status`

Show test and mutation testing status for a project.

```bash
vary status
vary status --trend
vary status --history
vary status --verify-cert <run-id>
```

| Flag | Description |
|------|-------------|
| `--trend` | Show mutation score trend |
| `--history` | Show run history |
| `--runs` | Show promoted runs |
| `--json` | Output as JSON |
| `--verify-cert` | Verify a mutation certificate by run ID |

### `vary aliases`

Manage CLI aliases created by `vary build --name`.

```bash
vary aliases           # list installed aliases
vary aliases remove myapp
```

#### `vary aliases remove`

| Flag | Description |
|------|-------------|
| `-f, --force` | Skip confirmation prompt |

## Installing

### `vary install`

Compile a Vary file or project to a JAR and install it as a command in `~/.vary/bin/`.

```bash
vary install app.vary
vary install app.vary --name myapp
vary install my-project/ --force
```

| Flag | Description |
|------|-------------|
| `--name` | Command name (default: project or file name) |
| `-f, --force` | Overwrite existing install |
| `-v, --verbose` | Verbose output |
| `-W, --warnings` | Warning mode: `all` (default), `none`, `error` |

### `vary uninstall`

Remove an installed command.

```bash
vary uninstall myapp
```

### `vary installs`

List all installed commands with metadata.

```bash
vary installs
```

## Environment

### `vary cache`

Manage the content-addressed artifact cache.

```bash
vary cache stats
vary cache ls
vary cache clear
vary cache gc
vary cache validate
vary cache inspect <artifact-id>
vary cache variants
```

#### `vary cache ls`

| Flag | Description |
|------|-------------|
| `-t, --variant` | Filter by variant: `normal`, `coverage`, `debug` |
| `-v, --verbose` | Show detailed information |

#### `vary cache clear`

| Flag | Description |
|------|-------------|
| `--older` | Only clear artifacts older than specified (e.g., `7d`, `24h`) |
| `-t, --variant` | Only clear specified variant |
| `-f, --force` | Skip confirmation prompt |

#### `vary cache gc`

| Flag | Description |
|------|-------------|
| `--strategy` | Eviction strategy: `lru` (default), `lfu` |
| `--max-size-mb` | Max cache size (overrides `vary.toml`) |
| `--max-age-days` | Max artifact age (overrides `vary.toml`) |
| `--dry-run` | Show what would be deleted |

#### `vary cache inspect`

| Flag | Description |
|------|-------------|
| `-t, --variant` | Filter by variant |
| `-v, --verbose` | Show full details |

### `vary client`

Generate a typed service client stub from `expose` statements. Inspects the exposed interface and produces `service` declarations with endpoints matching the server's routes.

```bash
vary client main.vary
vary client main.vary -o client.vary
```

| Flag | Description |
|------|-------------|
| `-o, --output` | Write output to a file instead of stdout |

### `vary routes`

Show HTTP routes for exposed interfaces. Parses and type-checks the file without running it. Accepts a `.vary` file or a project directory (resolves the entry point from `vary.toml`).

```bash
vary routes main.vary
vary routes .              # uses [build].entry from vary.toml
vary routes main.vary --json
vary routes main.vary --curl
```

| Flag | Description |
|------|-------------|
| `--json` | Machine-readable JSON output |
| `--curl` | Print copy-paste curl examples |

### `vary inspect`

Inspect compiler internals for debugging.

```bash
vary inspect tokens src/main.vary
vary inspect ast src/main.vary
```

### `vary vast`

Run VAST differential testing: generate random programs and compare AST interpreter output against JVM bytecode output.

```bash
vary vast
vary vast --profile control --count 100 --seed 42
vary vast --seed 842193 --count 1 --verbose
```

| Flag | Description |
|------|-------------|
| `-p, --profile` | VAST profile (`core`, `control`, `types`, `complete`, etc.). Default: `core` |
| `-n, --count` | Number of programs to generate. Default: 100 |
| `-s, --seed` | Base random seed. Default: clock-based |
| `-v, --verbose` | Show generated source and execution details |
| `--mode` | CI mode: `explore`, `fast`, `deep`, `continuous`, `rc-blocking` |
| `--lane` | Lane name for nightly metrics tagging |
| `--show-lanes` | Print nightly lane registry and exit |
| `--verify-config` | Verify CI mode configuration invariants |
| `--check-acceptance` | Check acceptance-set coverage in the corpus |
| `--closeout-report` | Generate VAST closeout report with evidence tiers and verdict |
| `--stateful` | Generate stateful programs with persistent mutable state |
| `--aliasing` | Generate heap aliasing verification programs |
| `--ir-check` | Verify IR translation equivalence |
| `--concurrency` | Generate concurrency semantics test programs |

Exit code 0 means all programs agreed. Exit code 1 means at least one mismatch or path failure. See [VAST CLI reference](/docs/vast/cli-reference/) for the complete flag list.

### `vary docs`

Generate Markdown documentation for all diagnostics and check rules.

```bash
vary docs
vary docs --output docs/diagnostics
```

| Flag | Description |
|------|-------------|
| `-o, --output` | Directory to write generated docs (default: `docs/diagnostics`) |

Generates an index page plus individual pages for each diagnostic code (E001, W002, etc.) and each check rule (VCI001, VCS001, etc.) with descriptions, examples, and fix guidance.

### `vary explain`

Show why a diagnostic or check rule exists, with examples and fix guidance.

```bash
vary explain E003
vary explain VCI001
vary explain W002
```

Takes a single diagnostic code as an argument. Prints the rule's rationale, a bad-code example, a good-code example, and related rules. Works for both compiler diagnostics (E/W codes) and check rules (VCI/VCC/VCT/VCM/VCS/VCA/VCL codes).

### `vary lsp`

Start the Language Server Protocol server for IDE integration.

```bash
vary lsp               # stdio mode (default)
vary lsp --port 9257   # socket mode
```

| Flag | Description |
|------|-------------|
| `-p, --port` | TCP port for socket mode (default: `0` for stdio) |
| `--log` | Log file path for debugging |

## Adaptive review loop

### `vary var`

Show adaptive review-loop status and drive validation iterations. Detects what changed, runs targeted checks/tests/mutation in a cost-aware pipeline, and reports what to fix next.

```bash
vary var                              # Show current status
vary var src/                         # Scope to src/ only
vary var --json                       # Machine-readable output
vary var --compact                    # Terse single-line output
vary var --dry-run                    # Preview what would run
vary var --dry-run --explain          # Preview with rationale
vary var --reset                      # Clear saved state, start fresh
vary var --since-ref main             # Only changes since main
vary var --max-cost low               # Cap iteration cost
vary var --include-mutation           # Include mutation testing
vary var --include-review-packet      # Include review-packet generation
```

| Flag | Description |
|------|-------------|
| `--json` | Output as JSON (schema version 1.0.0) |
| `--compact` | Compact single-line output for scripting |
| `--reset` | Clear saved state and start fresh |
| `--no-state` | Run without reading or writing session state |
| `--dry-run` | Preview actions without executing them |
| `--explain` | Show rationale for each planned action (with `--dry-run`) |
| `--since-ref <ref>` | Only consider changes since `<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 |

Positional arguments are paths to scope the change set (default: `.`).

**Pipeline stages:** The command runs up to six stages in order: discovery, check, test, mutation, review, and terminal classification. A cost-aware decision policy determines which stages run, skip, or block based on change significance and the `--max-cost` budget. Trivial changes (docs-only, config-only) skip deeper stages; critical changes run the full pipeline.

**Session state:** By default, `vary var` persists pipeline progress to `.vary-var-session.json` in the project root. Re-invoking resumes from the last completed stage unless the working tree has changed (detected via change fingerprint), in which case it resets to rediscovery. Use `--reset` to force a fresh start or `--no-state` to skip persistence entirely.

**Output modes:** The default human-readable output shows a staged report with color-coded pass/fail indicators, blocker listings, and a next-step recommendation with the exact command to run. `--json` produces a versioned schema suitable for CI integration. `--compact` produces a terse multi-line format parseable with simple text tools.

For full documentation, see the [VAR section](/var/).

## Global options

These flags work on all commands:

| Flag | Description |
|------|-------------|
| `-h, --help` | Show help for a command |
| `-V, --version` | Print the compiler version |