Native and npm CLI

Product surfaces

Product	Command surface
Native	complete source runtime, SICP, formatting, MCP, Meaning Graph, Core IR, bytecode, Rust VM, installed Topaz VM and AOT routes, images, receipts, and the full Vouch chain
npm CLI	source runtime through WebAssembly, images, structural receipt verification, replay, policy tools, Vouch authentication, and inspection

Run lispex --help or lispex <family> --help for flags accepted by the installed version.

Source and authoring

Command	Reads	Produces
`lispex [FILE\|-]`	Lispex source	reference-interpreter value, stdout, warnings, and diagnostics
`lispex sicp run <file.scm\|->`	one SICP source up to 1 MiB	SICP stdout and final value
`lispex fmt [--check\|--write] [FILE\|-]`	UTF-8 Lispex source	formatted source, quiet check status, or atomic in-place replacement
`lispex mcp serve`	framed local stdio requests	language and registry reference, authoring evaluation, diagnostics, and fixed route comparisons

The MCP authoring evaluator uses declared byte and time limits. Native owns this local authoring surface. The host application owns workspace paths, network access, and external actions.

Meaning Graph and Core IR

Command	Reads	Produces
`lispex lower --graph-version v1 SOURCE`	exact source through validated Core IR	canonical resolved Meaning Graph v1
`lispex eval-graph [--steps N] [--trace] GRAPH`	Meaning Graph v0 or v1 and optional input	tag-selected Meaning report with terminal status and optional trace
`lispex meaning-diff [--input I] SOURCE`	source and optional datum	current Rust tree and Meaning observations in `csk.meaning-differential-report/v1`
`lispex core-ir build --source S --out O`	exact source	canonical resolved `lispex.core-ir/v1` and summary
`lispex core-ir inspect --ir IR`	Core IR	resolved cells, captures, requirements, anchors, and identities
`lispex core-ir validate --ir IR`	Core IR	strict validation and canonical re-encode result

Core IR build, inspect, and validate report execution: "not-run" and authority: "integrity-only". Execution begins with the explicit runtime, Meaning, bytecode, or Vouch command selected by the user.

Bytecode and runtime routes

Command	Reads	Produces
`lispex bytecode build --ir IR --out O`	strict Core IR	verified canonical `.lpxbc` and summary
`lispex bytecode inspect --bytecode BC`	verified bytecode	identities, counts, requirements, opcodes, roots, and source-map coverage
`lispex bytecode validate --bytecode BC`	bytecode	strict decode, verify, and canonical re-encode result
`lispex bytecode run --bytecode BC [--input I]`	verified bytecode and optional datum	Rust VM observation
`lispex bytecode run --engine topaz --topaz-vm ROOT ...`	installed Topaz product, bytecode, and optional datum	Topaz VM observation under the named resource profile
`lispex run --backend rust --engine tree\|vm FILE`	Lispex source	explicitly selected Rust tree or VM observation
`lispex compare-engines --receipt R FILE`	Lispex source	atomic same-lineage tree and Rust VM comparison report
`lispex compare-vms --topaz-vm ROOT --receipt R FILE`	source and installed Topaz VM	atomic Rust and Topaz VM comparison report

The selected route retains its own error, resource, and lineage status. The comparison reports keep semantic, resource, and provenance fields separate.

Installed Topaz products

Command	Reads	Produces
`lispex routes install ...`	exact catalog entry and stored-ZIP archive	closed product directory and `installation.json`
`lispex routes fetch --route topaz-vm\|aot-compiler ...`	Native embedded official catalog	HTTPS acquisition and the same closed installation
`lispex routes lock ...`	reviewed installed route	canonical selection lock
`lispex routes run --selection LOCK ...`	selection lock and source	observation from the locked route
`lispex aot build --source S ... --out O`	exact source and absolute build tools	source-free Native product with tool identities
`lispex aot inspect\|validate --product P`	installed AOT product	inventory, identity, and derivation result
`lispex aot run --product P [--input I] [--json]`	installed product and resource request	direct executable observation
`lispex compare-routes ... --receipt R SOURCE`	exact source, input, Topaz VM, and AOT product	atomic four-route semantic, resource, and lineage report

Images

Command	Produces
`lispex image encode --source SOURCE --out IMAGE`	canonical `.lspx.png` or `.lspx-images.zip`
`lispex image inspect --image IMAGE`	format, profile, page, identity, and commitment summary
`lispex image decode --image IMAGE --out SOURCE`	exact recovered source
`lispex run --image IMAGE`	reference-interpreter observation of recovered source

Vouch commands that accept source context allow exactly one of --source RULE and --source-image IMAGE. Re-execution and gating pair that source with the separately supplied --input INPUT.

Receipts and Vouch

Command	Produces
`lispex diff-receipt --input I RULE`	`csk.differential-receipt/v0`
`lispex verify RECEIPT [--source RULE]`	offline structural consistency verdict
`lispex replay CORPUS --against BASELINE`	changed-decision report
`lispex vouch policy create\|check ...`	canonical recipient trust policy and validation report
`lispex vouch issue ...`	signed payload, DSSE envelope, and issue report
`lispex vouch verify ...`	authentication report for the exact signed context
`lispex vouch verify --reexecute ...`	authentication plus current tree and Meaning agreement
`lispex vouch gate --require-decision ...`	live local grant or denial and gate report
`lispex vouch compiled build ... --out A`	source-bound `lispex.vouch-compiled-artifact/v1` and summary
`lispex vouch compiled inspect --artifact A`	container and embedded-bytecode integrity summary
`lispex vouch compiled validate ...`	exact source→Core IR→bytecode derivation result
`lispex vouch verify --reexecute --compiled-artifact A`	current tree, Meaning, and verified Rust VM agreement
`lispex verify-bridge REPORT`	Bridge structure and receiver-selected byte-binding verdict

The compatibility names receipt, issue-native, verify-native, and the flat verify retain their published artifact contracts. Namespaced vouch commands provide the authenticated workflow.

Exit status and publication

Exit 0 means the requested operation succeeded.
Exit 10 on authenticated Vouch routes means authentication succeeded and the gate or diagnostic-promotion stage withheld admission.
Exit 1 reports validation, runtime, comparison, or authentication rejection.
Exit 2 reports usage, selected-engine, or resource handling errors.
Exit 3 reports input/output or named-report publication errors.

Named artifacts and reports are published atomically to a new path. JSON artifacts keep stdout byte-clean. The host application consumes a local gate result and owns the resulting external action.

Bytecode and Rust VM · Core IR Contract · Choosing Where to Run