GitHub

CLI

Global Flags

Flag Description
--verbose Enable structured timing output to stderr

Commands

Running a program

There is no nexus run subcommand. Compile with nexus build, then run the produced WASM directly under wasmtime:

nexus build program.nx -o out.wasm
wasmtime run -W tail-call=y,exceptions=y,function-references=y,stack-switching=y,threads=y --dir=. out.wasm

Determinism hooks are environment variables read at runtime, passed through wasmtime’s --env:

Env var Effect
NEXUS_SEED=N Fix the RNG seed for deterministic random output
NEXUS_FROZEN_CLOCK=EPOCH_MS Pin wall/mono clock to EPOCH (in milliseconds)
wasmtime run --env NEXUS_SEED=1 --env NEXUS_FROZEN_CLOCK=0 -W tail-call=y,exceptions=y,function-references=y,stack-switching=y,threads=y --dir=. out.wasm

nexus build FILE

Compile to a WASM component:

nexus build program.nx                  # outputs out.wasm
nexus build program.nx -o output.wasm   # custom output path

Build bundles deps automatically; wasm-merge just needs to be on the PATH.

Inspect declared caps:

nexus build program.nx --explain-capabilities           # list capability names (default)
nexus build program.nx --explain-capabilities=none      # suppress capability output
nexus build program.nx --explain-capabilities=wasmtime  # show wasmtime run command

Output format:

nexus build program.nx --explain-capabilities-format=text  # human-readable (default)
nexus build program.nx --explain-capabilities-format=json  # machine-readable JSON

Run the built component:

wasmtime run -Scli out.wasm
wasmtime run -Scli -Shttp -Sinherit-network -Sallow-ip-name-lookup -Stcp out.wasm

nexus typecheck FILE

Parse and typecheck only. No run, no WASM output.

nexus typecheck program.nx

Structured JSON output for CI, scripts, and LLM tool use:

nexus typecheck --format json program.nx
{
  "file": "program.nx",
  "ok": false,
  "diagnostics": [
    {
      "range": {
        "start": { "line": 5, "character": 9 },
        "end": { "line": 5, "character": 16 }
      },
      "severity": "error",
      "message": "Mismatch: string vs i64"
    }
  ],
  "symbols": [
    {
      "name": "main",
      "kind": "function",
      "range": {
        "start": { "line": 0, "character": 0 },
        "end": { "line": 10, "character": 3 }
      }
    }
  ]
}

The exit code is 0 on success and 1 if any error shows up. A warning alone does not fail the run.

LSP server

The LSP server is a separate binary, lsp.wasm, built by ./bootstrap.sh (Stage L). It is not a nexus subcommand. Run it over stdio under wasmtime; any LSP-aware editor can connect: VS Code, Neovim, Emacs, Helix, and so on.

wasmtime run -Scli lsp.wasm

Supported LSP features:

Feature Method Description
Diagnostics publishDiagnostics Parse errors, type errors, warnings on open/change
Hover textDocument/hover Type info for variables, functions, types, enums
Go to Definition textDocument/definition Jump to definition (same file)
Document Symbols textDocument/documentSymbol List functions, types, enums, caps, exceptions
References textDocument/references Find all occurrences of an identifier
Rename textDocument/rename Rename an identifier across the file
Completion textDocument/completion Keywords, env symbols, module members

The server walks up from the file to the nearest .git directory and uses that as the project root.

nexus repl

Launch an interactive session:

nexus repl

Each input line is parsed, typechecked, and run against a persistent session. A binding made at one prompt is visible at the next. Press Ctrl-D to exit.

Capabilities

Caps are declared in source with require { ... }. They never come from the command line. Inspect what a program requires with nexus caps or at build time:

nexus caps main program.nx                              # caps required by a symbol
nexus build program.nx --explain-capabilities           # list capability names
nexus build program.nx --explain-capabilities=wasmtime  # show wasmtime run command
nexus build program.nx --explain-capabilities=none      # suppress capability output

Most caps (Console, Random, Clock, Proc, Env) are static, compile-time checks only. At run time, only Fs and Net are enforced through wasmtime flags: --dir . grants Fs, --wasi inherit-network grants Net. Omit the flag to deny the capability.

See WASM and WASI for the per-cap WASI mapping.