CLI reference

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

vary <command> [options]

Running code

vary run

Compile and run a Vary file.

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

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

vary repl

Start an interactive read-eval-print loop.

vary repl

vary dev

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

vary dev
vary dev app.vary
vary dev --port 8080

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).

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

See Check rules for the full list of shipped rules and what each one detects.

vary fmt

Format source files. Zero configuration, one style.

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

vary loc

Count lines of Vary code in a file or directory.

vary loc
vary loc src/

Testing

vary test

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

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

vary mutate

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

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

See 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.

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

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.

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

The benchmark fails on any cross-mode classification mismatch, empty killedBy for a killed mutant, or flaky classification across identical runs. See Benchmark for the parity model and metrics.

vary validate

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

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

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 for details.

Building

vary build

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

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

Project management

vary new

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

vary new my-app
vary new my-app --force
vary new my-app --devcontainer
vary new my-app --template 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.

vary init
vary init --name my-project

vary config

Print the resolved project configuration.

vary config
vary config --verbose

vary status

Show test and mutation testing status for a project.

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

vary aliases

Manage CLI aliases created by vary build --name.

vary aliases           # list installed aliases
vary aliases remove myapp

vary aliases remove

Installing

vary install

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

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

vary uninstall

Remove an installed command.

vary uninstall myapp

vary installs

List all installed commands with metadata.

vary installs

Environment

vary cache

Manage the content-addressed artifact cache.

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

vary cache clear

vary cache gc

vary cache inspect

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.

vary client main.vary
vary client main.vary -o client.vary

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).

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

vary inspect

Inspect compiler internals for debugging.

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.

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

Exit code 0 means all programs agreed. Exit code 1 means at least one mismatch or path failure. See VAST CLI reference for the complete flag list.

vary docs

Generate Markdown documentation for all diagnostics and check rules.

vary docs
vary docs --output 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.

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.

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

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.

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

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.

Global options

These flags work on all commands: