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

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.

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

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

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

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.

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

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.

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)
--fast-mode	Heuristic narrowing of the coverage-guided test filter, validated each run with automatic fallback when miss rate exceeds threshold (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 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

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.

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

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

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

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.

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.

vary config
vary config --verbose

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

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>

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.

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

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.

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

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.

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

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.

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

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 for the complete flag list.

vary docs

Generate Markdown documentation for all diagnostics and check rules.

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.

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

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.

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.

Global options

These flags work on all commands:

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