Choose a Lispex command for your task, then check its inputs, results, and exit status. Native and npm both run source files; Native also provides the compilation and engine commands listed below.
Install Lispex using First Program or Downloads. See the Product Catalog for platform availability.
Run a file
Save this complete program as answer.lspx.
(+ 20 22)Run it with Native or npm.
lispex answer.lspxOutput
42The command exits with status 0 and creates no files.
For the installed version's commands and flags, lispex --help prints the command list.
A command family's help, such as lispex vouch --help, describes that family's options.
Reading the command tables
The tables show command syntax and expected results. Linked guides provide complete workflows.
Uppercase names such as SOURCE, IR, and ROOT stand for paths you supply.
Brackets mark optional arguments, | separates alternatives, and ... stands for additional required or optional flags.
An input datum is one Lispex value read from a file.
Source and authoring
| Command | Reads | Produces | Product |
|---|---|---|---|
lispex [FILE|-] | Lispex source | Values, standard output, warnings, and diagnostics | Native, npm |
lispex sicp run <file.scm|-> | One SICP source up to 1 MiB | SICP standard output and final value | Native, npm |
lispex fmt [--check|--write] [FILE|-] | UTF-8 source | Formatted source, check status, or replacement of the original file | Native |
lispex mcp serve | Framed requests over local standard input and output | Language and procedure reference, evaluation, diagnostics, and fixed engine comparisons | Native |
The MCP service evaluates trusted source under declared byte and time limits. The calling application controls workspace paths, network access, and external actions. See MCP for its request protocol. Formatting replaces a file atomically, so a completed replacement appears as one operation.
Meaning Graph and Core IR — Native
Core IR is an intermediate representation that resolves name references. Meaning Graph represents program operations as nodes that the Meaning evaluator can execute. Canonical files use one prescribed byte representation.
| Command | Reads | Produces |
|---|---|---|
lispex lower --graph-version v1 SOURCE | Exact source, converted through validated Core IR | Canonical Meaning Graph v1 with resolved name references |
lispex eval-graph [--steps N] [--trace] GRAPH | Meaning Graph v0 or v1 and optional input | A report selected by the graph's version tag, with terminal status and optional trace |
lispex meaning-diff [--input I] SOURCE | Source and optional input datum | Current Lispex Interpreter and Meaning results in csk.meaning-differential-report/v1 |
lispex core-ir build --source S --out O | Exact source | Canonical lispex.core-ir/v1 file and summary |
lispex core-ir inspect --ir IR | Core IR | Variable cells, captured variables, requirements, source locations, and identifiers |
lispex core-ir validate --ir IR | Core IR | Strict validation, including re-encoding in the prescribed format |
Core IR build, inspect, and validate report execution: "not-run" and authority: "integrity-only".
They create or check a representation. Select a runtime, Meaning, bytecode, or Vouch execution command to run the program.
Core IR shows a complete source-to-file example.
Bytecode and engine comparisons — Native
A virtual machine, or VM, executes prepared instructions called bytecode.
| Command | Reads | Produces |
|---|---|---|
lispex bytecode build --ir IR --out O | Validated Core IR | Verified canonical .lpxbc file and summary |
lispex bytecode inspect --bytecode BC | Verified bytecode | Identifiers, counts, requirements, instructions, entry points, and source-map coverage |
lispex bytecode validate --bytecode BC | Bytecode | Strict decoding, verification, and canonical re-encoding result |
lispex bytecode run --bytecode BC [--input I] | Verified bytecode and optional input datum | Lispex VM result, output, and diagnostics |
lispex run --backend rust --engine tree|vm FILE | Lispex source | Result from the selected Lispex Interpreter or VM |
lispex compare-engines --receipt R FILE | Lispex source | Comparison report for the Lispex Interpreter and VM implementations |
Each execution method retains its own error and resource status. Reports record program behavior, resource usage, and source and producer information separately. Comparison reports are written atomically to a new path. Run Verified Bytecode supplies complete commands and output.
Resource-controlled evaluation — Native
The decision evaluator and full evaluator are separate products. Preparation reads source and limits to create a prepared file. Evaluation reads that file, a binary input value, and evaluation limits to create a result file.
| Command family | Result and follow-up operations |
|---|---|
lispex embed prepare, evaluate, inspect, verify | Decision-profile preparation and evaluation files; JSON inspection and integrity checks |
lispex embed full prepare, evaluate, inspect, verify, replay | Full-profile files; JSON inspection, integrity checks, and fresh-instance replay |
lispex rule run, inspect, verify, replay | A five-file decision directory and operations on that directory |
To rerun a decision-profile evaluation, supply the same inputs to embed evaluate again, or use rule replay on a decision directory.
Run a Rule Within Set Limits includes every input file, command, and result.
Images — Native and npm
| Command | Produces |
|---|---|
lispex image encode --source SOURCE --out IMAGE | Canonical .lspx.png or .lspx-images.zip |
lispex image inspect --image IMAGE | Summary of format, profile, pages, source identifiers, and integrity bindings |
lispex image decode --image IMAGE --out SOURCE | Exact recovered source |
lispex run --image IMAGE | Reference-interpreter result, output, and diagnostics for the recovered source |
Lispex Images shows encoding and recovery.
Vouch commands with source context accept exactly one of --source RULE and --source-image IMAGE.
Re-execution and local approval use that source with the separately supplied --input INPUT.
Comparison records and Lispex Vouch
A differential receipt records a comparison. Lispex Vouch adds authentication of signed records. Native provides the full Vouch workflow. npm provides record inspection, offline authentication, recipient-policy tools, and comparison of recorded cases.
| Command | Produces | Product |
|---|---|---|
lispex diff-receipt --input I RULE | Comparison record in csk.differential-receipt/v0 | Native |
lispex verify RECEIPT [--source RULE] | Offline structural consistency verdict | Native, npm |
lispex replay CORPUS --against BASELINE | Report comparing recorded decisions against a version or record directory | Native, npm |
lispex vouch policy create|check ... | Canonical recipient trust policy or validation report | Native, npm |
lispex vouch issue ... | Signed data, a DSSE signed-record container, and issue report | Native |
lispex vouch verify ... | Authentication report for the exact signed context | Native, npm |
lispex vouch verify --reexecute ... | Authentication and current Lispex Interpreter and Meaning agreement | Native |
lispex vouch gate --require-decision ... | Live local grant or denial and gate report | Native |
lispex vouch compiled build ... --out A | Source-bound lispex.vouch-compiled-artifact/v1 and summary | Native |
lispex vouch compiled inspect --artifact A | Integrity summary for the container and embedded bytecode | Native |
lispex vouch compiled validate ... | Check that exact source derives the recorded Core IR and bytecode | Native |
lispex vouch verify --reexecute --compiled-artifact A | Current tree, Meaning, and verified Lispex VM agreement | Native |
lispex verify-bridge REPORT | Bridge report structure and receiver-selected byte-binding verdict | Native, npm |
The compatibility names receipt, issue-native, verify-native, and the top-level verify keep their published file formats and behavior.
The vouch command family provides the authenticated workflow.
See Lispex Vouch for the complete process.
Exit status and saved files
Interpret the exit status together with the command's result.
| Command or outcome | Status |
|---|---|
| Requested operation succeeded | 0 |
| Validation, execution, comparison, or authentication rejected | Usually 1; inspect the diagnostic |
fmt --check found formatting changes | 1, with no formatted output |
| Invalid usage, unavailable selected engine, or ordinary source execution reaching a resource limit | 2 |
| Input/output or named-report publication failed | 3 on commands that use this code |
| Authenticated Vouch request withheld at the local gate or diagnostic-promotion step | 10 |
Diagnostic promotion determines whether an authenticated record qualifies for the next approval step.
Authentication has succeeded when these Vouch commands return 10.
Embed evaluation reports success, a program fault, or resource exhaustion inside its saved result.
When that result is saved successfully, these outcomes return 0.
Read inspect to distinguish them. Rejected requests can return 3, and evaluator or record-construction failures can return 4.
See Evaluator Reference for the separate category names.
Commands that publish a named new record or report write it atomically and refuse to overwrite an existing path. For JSON output, diagnostics are kept separate from the JSON bytes on standard output. The calling application reads a local gate result, then decides and performs any external action.