nova CLI

Quickstart

# Inside a Nova project (nova.toml nearby):
nova check                       # type-check the whole workspace
nova check src/                  # recursively check a directory
nova check src/lib.nv            # single file

nova run hello.nv                # run via interpreter
nova build app.nv -o app         # compile to native binary
nova test                        # run all nova_tests/
nova test --filter basics        # run subset by substring

nova doc src/lib.nv              # markdown to stdout
nova doc src/ --format json      # JSON schema (D107)
nova doc src/ --check --strict   # CI doc validation

nova bench run bench.nv          # run benchmarks
nova contracts verify foo.nv     # SMT contract verification

Install & Build

nova-cli lives in nova-cli/ alongside compiler-codegen/. Both crates are standalone (no shared workspace).

# Debug build (default, opt-level=0)
cargo build --manifest-path nova-cli/Cargo.toml

# Release (opt-level=2, LTO thin)
cargo build --release --manifest-path nova-cli/Cargo.toml

# With Z3 backend for contracts (Plan 33.1)
cargo build --release --manifest-path nova-cli/Cargo.toml --features z3-backend

Outputs:

• nova-cli/target/{debug,release}/nova[.exe]
• nova-cli/target/{debug,release}/migrate_plan60[.exe]
• nova-cli/target/{debug,release}/migrate_plan65[.exe]

nova has a path-dependency on nova_codegen (../compiler-codegen) — rebuilding the compiler automatically recompiles the CLI.

Global Flags

Apply to all subcommands:

Color auto-detection (priority high → low):

1. CLI --color always|never — forced
2. CLICOLOR_FORCE=1 → always
3. NO_COLOR (any value) → never
4. CLICOLOR=0 → never
5. CI=true → never
6. TERM=dumb → never
7. Default — enabled

Exit Codes

nova doc --diff additionally uses 3 = patch-level change. See nova doc.

Project Root Discovery

Most commands search for nova.toml upward from CWD. This is workspace-aware (D78 AD6):

1. Walk upward from CWD to filesystem root.
2. At each level read nova.toml if present.
3. If it contains [workspace] — this is the workspace root; stop.
4. Otherwise remember the last found nova.toml and continue.
5. Return the workspace root if found; otherwise the topmost nova.toml.

Protects against nested nova_tests/nova.toml shadowing the main project root. If no nova.toml is found — exit 2:

error: nova.toml not found — are you inside a Nova project?

Paths resolved under workspace root: nova_tests/, std/, compiler-codegen/, target/last-test-results.json.

nova check

Type-check one or more .nv files or directories.

nova check [PATHS...] [--jobs N] [-q|-v] [--list] [--format human|short]
           [--include-runtime] [--skip PATTERN]...

Always skipped: target/, node_modules/, vendor/, .git/, .hg/, .svn/, dirs starting with _ or ., std/runtime/.

Summary: pass=N fail=N warnings=N (X.YYs). Exit 1 on any FAIL.

nova run

Run a .nv file via the interpreter (no native compilation).

nova run FILE

FILE must be a .nv file with fn main.

nova build

Compile one .nv file to a native binary via the C backend.

nova build FILE [-o OUTPUT] [--mode dev|release] [--toolchain auto|clang|msvc|gcc]
           [--vcvars PATH] [--clang PATH] [--timeout SECS] [--keep-artifacts]
           [--mono-depth N]

One file at a time. For multi-file projects use import inside the entry-point.

Pipeline: parse + typecheck + infer_effects → C emit → toolchain detect → libuv detect/build → compile → copy to output → cleanup tmp.

nova test

Run tests from a directory or file.

nova test [PATH] [--filter SUBSTR] [--jobs N] [--format text|json|tap|junit]
          [--mode dev|release] [--toolchain auto|clang|msvc|gcc]
          [--vcvars PATH] [--clang PATH] [--timeout SECS] [-v|-q]
          [--results-file PATH] [--rerun-failed] [--retries N]
          [--include-stdlib] [--keep-artifacts] [--gc boehm|malloc]
          [--list] [--filter-from PATH] [--shuffle [SEED]]
          [--skip PATTERN]... [--mono-depth N]

Output formats: text (human, colored), json (array with name/status/duration_ms/stderr), tap (TAP v13), junit (JUnit XML for CI aggregators).

EXPECT markers in test files:

• // EXPECT: <stdout-line> — exact stdout line match
• // EXPECT_STDERR: <line> — stderr match
• // EXPECT_COMPILE_ERROR: <substring> — must fail at compile time
• // EXPECT_RUNTIME_ERROR: <substring> — panic with substring
• // REQUIRES_SMT_BACKEND — skip if SMT unavailable

nova test-build

Build and run a single test file. For IDE / CI point-debugging.

nova test-build FILE [--mode dev|release] [--toolchain auto|clang|msvc|gcc]
                [--vcvars PATH] [--clang PATH] [--timeout SECS]
                [--keep-artifacts] [--gc boehm|malloc] [--mono-depth N]

Equivalent to nova test <FILE> but without bulk-runner machinery. Defaults: --timeout 60, --gc boehm, --mono-depth 500.

nova regen-runtime

Regenerate std/runtime/*.nv stubs from the compiler-runtime registry. Replaces the old regen_runtime.ps1.

nova regen-runtime [--check]

nova doc

Production-grade documentation generator (Plan 45 / D107). Supports Markdown, JSON, and HTML output, doc-tests, coverage metrics, watch mode, workspace mode, API diff, and contract mutation testing.

nova doc [FILE] [--format markdown|json|html] [--json-schema]
         [--include-private] [--test] [--check] [--watch]
         [--coverage [--coverage-threshold PERCENT]] [--jobs N]
         [--diff OLD NEW] [--scrape-examples WORKSPACE]
         [--strict] [--mutate-contracts [--real-exec]]
         [--output-dir DIR]

Exit codes for --diff OLD NEW:

Mutation testing (--mutate-contracts): generates mutants per function with contracts (>↔>=, ==↔!=, dropping requires/ensures). Default — text heuristic (~1 ms/mutant). With --real-exec — runs mutated doc-tests (~100 ms/mutant, true-positive guarantee).

Doc-comments

Two comment styles:

• /// (outer) — applies to the next declaration.
• //! (inner) — applies to the entire module.

//! Module-level doc — describes the entire file.

module my.module

/// One-sentence summary ending with a period.
///
/// Longer description below. Can span multiple lines.
///
/// # Examples
///
/// ```nova
/// let x = double(3)
/// assert(x == 6)
/// ```
export fn double(x int) -> int => x * 2

Sections

Standard sections are recognized and rendered in fixed order (D107):

Other # Heading sections are preserved as part of the current section's text.

Intra-doc Links

/// Returns a [Point] for the coordinate.
/// See also [translate] and [std.math.abs].

Resolution:

• [Name] — short match by item-id.
• [Type.method] — short method form.
• [mod.path.Name] — fully qualified.

Broken links produce target_id: null in JSON and a message from nova doc --check.

Doc-tests

```nova blocks in doc-comments are doc-tests, executed by nova doc --test.

Modifiers

```nova,no_run        — compile but do not run
```nova,ignore        — do not compile (display only)
```nova,compile_fail  — expect a compile error
```nova,should_panic  — expect a runtime panic
```nova,must_verify   — expect successful SMT verification

Modifiers can be combined: ```nova,no_run,ignore.

Hidden Lines

Lines starting with # are hidden in rendered output but included in compilation:

/// ```nova
/// # import std.io
/// let r = compute()
/// assert(r == 42)
/// ```

Stability & Deprecation

Via sections (version-based):

/// API.
///
/// # Since
///
/// 1.0.0
export fn add(a int, b int) -> int => a + b

# Since >= 1.0 → stability.tier = "stable", otherwise unstable.

Via doc-attrs (D96 attribute syntax #name(...) — written between the doc-comment and the declaration, not inside ///):

/// Experimental API.
#experimental(note = "may change in 0.5")
#since("0.3.0")
export fn experimental_api() -> int => 0

#deprecated takes precedence over a # Deprecated section.

JSON Output

D107 schema v1. Keys in alphabetical order, byte-for-byte deterministic. Top-level fields:

• format_version: 1
• nova_version: "0.1.0"
• generated_at — omitted by default; controlled by NOVA_DOC_GENERATED_AT or SOURCE_DATE_EPOCH.
• doc_tests[] — extracted ```nova blocks.
• links[] — intra-doc links (resolved + broken).
• modules[] — DocModule entries.
• items[] — DocItem entries (fn / type / const / effect / protocol).

Run nova doc --json-schema for the full JSON Schema 2020-12 specification.

jq Recipes

# All public fn with summaries
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.kind=="fn" and .visibility=="export") | {id,summary}]'

# Items without summaries (undocumented)
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.summary == null) | .id]'

# All #unstable or #experimental items
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.stability.tier != null and .stability.tier != "stable") | {id, tier: .stability.tier}]'

# All #deprecated items with replacement note
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.deprecation != null) | {id, note: .deprecation.note}]'

# Functions with @realtime capability
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.capabilities.realtime==true) | .id]'

# Functions with SMT contracts (Proven)
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.signature?.verify_status=="proven") | .id]'

# All re-exports with doc_inline=true
nova doc src/api.nv --format json \
  | jq '[.items[] | select(.kind=="reexport" and .doc_inline==true) | {id, source: .reexport_from}]'

# Items with scraped examples
nova doc src/api.nv --format json --scrape-examples . \
  | jq '[.items[] | select(.scraped_examples | length > 0) | {id, count: (.scraped_examples | length)}]'

# All broken intra-doc links
nova doc src/api.nv --format json \
  | jq '[.links[] | select(.target_id == null) | .text]'

# Semver diff: list major changes
nova doc --diff old.json new.json 2>&1 | grep '\[major\]'

CI Integration

# Validate doc (broken links, missing summaries)
nova doc src/api.nv --check

# Run doc-tests (exit 1 on failure)
nova doc src/api.nv --test

# Reproducible builds
SOURCE_DATE_EPOCH=1700000000 nova doc src/api.nv --format json > api.json

Style Guide (§11.5)

1. First sentence — summary, terminated with ..
2. Imperative mood: "Returns X" not "This function returns X".
3. Fixed section order (see table above).
4. Markdown subset: CommonMark + ```nova fenced blocks.
5. Examples required for all public fn.
6. Deprecation note includes replacement + # Since.
7. Stability tiers: stable / unstable / experimental.

nova doc-query

DSL queries over nova doc --format json output (Plan 45). Foundation for the MCP server.

nova doc-query JSON_FILE [QUERY]

Query syntax: key=value,key=value,...

nova doc src/ --format json > out.json
nova doc-query out.json "kind=fn,capability=pure"
nova doc-query out.json "name=add,has-contracts=true"
nova doc-query out.json "module-prefix=std,effect=Fs"

Empty query returns the full file as-is.

nova doc-mcp

MCP server (Model Context Protocol) — JSON-RPC over stdio or HTTP. Compatible with MCP clients (Claude Code, MCP Inspector).

nova doc-mcp FILE [--port PORT]

Exported tools (via tools/list):

• query_items(query) — search via DSL (see nova doc-query)
• list_modules() — list module paths
• get_item(item_id) — full JSON for a single item

Protocol: MCP client sends initialize → tools/list → tools/call.

nova contracts

Contract inspection and verification (Plan 33 / D24). Output — JSON (AI-friendly schema, see docs/contracts-diag-schema.json).

nova contracts list

List all contracts in a file.

nova contracts list FILE

nova contracts verify

SMT-verify contracts. Requires build with --features z3-backend for the Z3 backend.

nova contracts verify FILE [--backend BACKEND]

nova contracts suggest

AI-assisted contract suggestions (stubs).

nova contracts suggest FILE FN_NAME

nova contracts counterexample

Counterexample for a failing contract.

nova contracts counterexample FILE FN_NAME [--contract-id N]

nova bench

Benchmark infrastructure (Plan 57). Subcommands:

run · diff · gate · calibrate · cpu-instr-check · membw-check · hyperfine · callgrind · callgrind-check · runner-branch · history-anomalies / history-add / history-list / history-squash · remote · corpus · dashboard

nova bench run

Run bench "..." { measure { ... } } declarations in a file.

nova bench run FILE [--filter PATTERN] [--samples N] [--warmup-ms MS]
                    [--time-budget SECS] [--gc boehm|malloc]
                    [--mode release|dev] [--toolchain auto|clang|msvc|gcc]
                    [--compile-timeout SECS] [--run-timeout SECS]
                    [--keep-artifacts] [--mono-depth N]
                    [--out PATH] [--out-csv PATH] [--out-md PATH]
                    [--out-criterion DIR] [--profile MODE OUT]
                    [--histogram]

Output formats: --out (JSON v1 with git SHA, toolchain, CPU model); --out-criterion (<dir>/<name>/new/{estimates,sample,benchmark}.json); --out-md (markdown table for PRs); --histogram (40 buckets, Unicode blocks, median + Tukey fences).

Profile modes: cpu — wraps in samply (needs cargo install samply); heap — NOVA_BENCH_HEAP_SAMPLE_MS=10; gc — NOVA_BENCH_GC_TRACE=1.

nova bench diff

Compare two bench results. Welch's t-test, geomean delta, reproducibility check.

nova bench diff BASELINE NEW [--format terminal|markdown|json]
                              [--explain [--ai-config PATH] [--ai-max-tokens N] [--ai-dry-run]]
                              [--baseline-sha SHA] [--new-sha SHA]

--explain uses system curl and requires NOVA_AI_API_KEY or config.

nova bench gate

CI gate: apply thresholds from bench.toml. Exit 0 = pass, 1 = regression.

nova bench gate BASELINE NEW [--config PATH] [--noise PATH]

nova bench calibrate

Auto-calibrate noise floor from ≥2 repeated runs of the same baseline.

nova bench calibrate RUNS... [--out PATH]

The noise file is machine-specific; do not commit to git.

nova bench cpu-instr-check

Diagnose CPU instruction counter availability. Linux: checks perf_event_open + measures a known loop. Other OS: stub message.

nova bench cpu-instr-check

nova bench membw-check

Diagnose memory-bandwidth measurement. Linux: probes /sys/devices/uncore_imc_* + LLC-miss perf counter. Other OS: stub.

nova bench membw-check

nova bench hyperfine

Hyperfine-style cross-binary wall-clock timing. Output compatible with nova bench diff.

nova bench hyperfine SPECS... [--warmup N] [--samples N]
                              [--timeout SECS] [--workdir PATH] [--out PATH]

nova bench hyperfine \
  "old=./nova-old build large.nv" \
  "new=./nova-new build large.nv" \
  --samples 10 --warmup 2 --out result.json

nova bench callgrind

Run under Valgrind Callgrind for deterministic CPU instruction count. Requires valgrind (macOS + Linux). Falls back to perf_event_open on Linux without Valgrind.

nova bench callgrind BINARY [ARGS...] [--cache-sim] [--workdir PATH] [--out PATH]

nova bench callgrind-check — verify Valgrind presence and version.

nova bench runner-branch — print the recommended history branch name based on NOVA_BENCH_RUNNER_ID (returns bench-history or bench-history-<id>).

nova bench remote

SSH-distributed bench coordination.

nova bench remote list [--config PATH]           # list remotes
nova bench remote ping NAME [--config PATH]      # SSH health-check
nova bench remote run BENCH [--remotes LIST] [--gather-into DIR] [--sha SHA] [--config PATH]

Remote config: ~/.nova-bench-remotes.toml (override via NOVA_BENCH_REMOTES).

nova bench corpus PATH — per-pass compile time measurement. Wraps nova build with NOVA_PERF_TIMER=1; parses __PERF__ markers. Flags: --json, --html PATH, --echarts-url URL, --mode, --toolchain, --gc.

nova bench history

Manage the orphan history branch for CI regression tracking.

# Append a result to the history branch
nova bench history-add RESULT [--branch BRANCH] [--push] [--remote NAME] [--dry-run]

# List entries (newest first)
nova bench history-list [--branch BRANCH]

# Squash old entries by date (recommended: yearly)
nova bench history-squash --before-date YYYY-MM-DD [--branch BRANCH] [--push] [--remote NAME] [--dry-run]

# Detect changepoints in historical median time-series (PELT algorithm)
nova bench history-anomalies [--branch BRANCH] [--format text|json]

Default history branch: bench-history (or bench-history-<NOVA_BENCH_RUNNER_ID> for multi-runner CI).

nova bench dashboard

Generate a static HTML dashboard from history.

nova bench dashboard [--history-branch BRANCH] [--out DIR] [--max-entries N] [--echarts-url URL]

Generates index.html + bench-<safe-name>.html per bench + data.json.

Environment Variables

Migration Binaries

One-shot lexer-based migration tools in nova-cli/src/bin/. Kept in the repository as a reference for future atomic API-rename plans.

migrate_plan60

Migrate field-style size accessors to method form (D117 / Plan 60):

migrate_plan60 [--apply] [--dry-run] [--md] [--paths DIR...]

Skip condition: previous significant token is = (method-value assignment). Comments, whitespace, and formatting are preserved token-for-token.

migrate_plan65

Migrate Time.after(<lit>) → ChanReader.close_after(Duration.from_*(<lit>)) (Plan 65 AD11):

migrate_plan65 [--apply] [--dry-run] [--md] [--paths DIR...]

Special exit codes: