Native and npm CLI

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

42

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

Connect an editor

Install the native binary and put lispex on your PATH. Start the language server with lispex lsp. It provides syntax diagnostics, formatting, document symbols, go to definition, completion, and built-in procedure descriptions. The language server reads only documents sent by the editor and does not run them.

The npm CLI prints the native installation address for lispex lsp and exits with status 2.

Helix

Add this to ~/.config/helix/languages.toml, then open a .lspx file. Run hx --health lispex to check that Helix finds the server.

[language-server.lispex]
command = "lispex"
args = ["lsp"]

[[language]]
name = "lispex"
scope = "source.lispex"
file-types = ["lspx"]
roots = []
language-servers = ["lispex"]
indent = { tab-width = 2, unit = "  " }

Neovim

Add this to init.lua, then open a .lspx file with Neovim's built-in LSP client.

vim.api.nvim_create_autocmd({ 'BufRead', 'BufNewFile' }, {
  pattern = '*.lspx',
  callback = function()
    vim.bo.filetype = 'lispex'
    vim.lsp.start({
      name = 'lispex',
      cmd = { 'lispex', 'lsp' },
      root_dir = vim.fn.getcwd(),
      capabilities = vim.lsp.protocol.make_client_capabilities(),
    })
  end,
})

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

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.

Core IR build, inspect, and validate do not run the rule. The build and inspection reports show execution: "not-run" and authority: "integrity-only". The validation report shows core_ir_validation: "lispex.core-ir-validation/v1" and valid: true. These commands create or check a representation. Select a runtime, Meaning, bytecode, or Vouch execution command to run the program. Compile a Rule to Bytecode shows a complete source-to-file example.

Bytecode and engine comparisons — Native

A virtual machine, or VM, executes prepared instructions called bytecode.

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. Compile a Rule to 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.

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.

Keys and decision exchange

Decision exchange delivers the result of a decision directory to a recipient as a signed bundle. The bundle contains no source and no private key.

The calling application keeps the private key and checks where a public key came from. Typesetting Rule Workspace walks through the whole process from key generation to replay.

Images — Native and npm

Create and Restore 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.

On Native, issue-native, verify-native, and verify-structure are compatibility names for vouch issue, vouch verify, and vouch inspect. On npm, the top-level verify and replay are compatibility names for vouch inspect and vouch replay. Native receipt also keeps its published record format and behavior. Comparison of recorded cases exists only in npm. Running lispex vouch replay on Native points to npm and exits with status 2. 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.

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.

If you find a problem, please report it as a GitHub issue with a rule and an input that reproduce it.