Skip to content
v0.6.11

CLI reference (lsc)

The lsc command drives the whole toolchain. Install it globally (npm install -g lemmascript) or run it from a source checkout with npx tsx tools/src/lsc.ts.

Terminal window
lsc <gen|gen-check|check|regen|extract|info> [--backend=lean|dafny] [flags] <file.ts>
lsc config [--config=path] [<file.ts>]
lsc <gen|gen-check|check> [--backend=…] [--slow] # no file: batch over LemmaScript-files.txt
lsc claimcheck [<file.ts>] [flags…] # forwards to lemmascript-claimcheck

All flags use the --flag=value form. Space-separated flags (--backend lean) and unknown flags are rejected with an error rather than silently ignored. Every command exits 0 on success and 1 on any failure.

CommandWhat it does
lsc gen <file.ts>Generate backend code (next to the source unless proof-dir is configured)
lsc gen-check <file.ts>gen, then verify the hand-edited file is additions-only vs. the generated one (Dafny)
lsc check <file.ts>gen + additions-only check + run the prover — the full loop
lsc regen <file.ts>Regenerate after a TS edit, three-way-merging to preserve proof additions (Dafny)
lsc extract <file.ts>Dump the Raw IR as JSON to stdout (backend-neutral)
lsc info <file.ts>Write <file>.ts.json, a per-function spec summary (backend-neutral)
lsc config [<file.ts>]Show the discovered config, effective options, and resolved Dafny artifact directory
lsc claimcheck [<file.ts>]Check each function’s plain-English //@ contract against its formal clauses
lsc runs [--json]Report what verification caught, from the run log

Generates backend files next to your TypeScript source unless a Dafny proof-dir is configured.

  • Dafny (--backend=dafny, the default): writes <name>.dfy.gen (always regeneratable — never edit) and, on first run, <name>.dfy (the file you and your proofs own; starts as a copy of .dfy.gen).
  • Lean (--backend=lean): writes <name>.types.lean (when the module declares types) and <name>.def.lean.

The whole loop for one file: generate, confirm the diff between <name>.dfy and <name>.dfy.gen is additions-only, then run the prover (dafny verify, or lake build for Lean). Passes only when every contract holds.

Terminal window
lsc check --backend=dafny src/domain.ts
lsc check --backend=dafny --time-limit=120 src/domain.ts
lsc check --backend=dafny --extra-flags="--isolate-assertions" src/domain.ts

After editing the TypeScript, regenerate without losing proof work: the new generated code is three-way-merged into <name>.dfy (using <name>.dfy.base), preserving your helper lemmas, ghost predicates, and asserts, then re-verified.

Never delete <name>.dfy and gen fresh — you’d lose every proof addition. regen is the safe path. Use --no-verify to run only the merge and additions-only check, skipping the prover (CI uses this when a separate check pass does the verifying).

Recovery state depends on the failure stage. A conflict restores the original proof and retains the old .dfy.base; an additions-only failure also retains that anchor. If the merge is clean and additions-only but verification fails, .dfy.base instead advances to the new generation already present in the proof. Keep it while fixing the proof. A successful regen removes the anchor, also under --no-verify. Do not discard an anchor solely because a command failed.

Backend-neutral: they run regardless of any //@ backend directive.

  • extract prints the structured Raw IR as JSON — the supported way for external tools to consume LemmaScript’s frontend instead of re-parsing TypeScript.
  • info writes <file>.ts.json: each function’s signature plus its requires / ensures / decreases clauses. Tools like lemmascript-seal build on this.

Discovers the nearest lemmascript.json above a source file and prints its effective options after top-of-file overrides. With a file, the report also contains the absolute Dafny artifact directory; without one, discovery starts at the current directory. Use --config=<path> to pin a particular file.

{
"extern-default": "impure",
"string-semantics": "unicode-scalar",
"dafny-library": "stdlib",
"safe-slice": true,
"proof-dir": "proofs",
"run-log": true
}

dafny-library selects stdlib (default) or generated local helpers for collection operations. Enabling "string-semantics": "javascript-utf16" requires explicitly setting "dafny-library": "local"; an omitted or explicit stdlib choice is an error.

run-log (default true) records every Dafny check and regen in .lemmascript/ beside lemmascript.json (without one, beside the nearest LemmaScript-files.txt, else at the git repository root, or else in the current directory): one line per run in runs.jsonl (the stage it stopped at and which members passed or failed) plus a snapshot of the source. The directory ignores itself in git, and logging never changes lsc output or exit codes. Set it to false to turn logging off for the project, or LSC_RUN_LOG=false for a single run. lsc runs reports what the log caught.

A file can override both project settings before its first statement:

//@ backend dafny
//@ option string-semantics javascript-utf16
//@ option dafny-library local

Source dependencies must use the same effective string model. lsc config file.ts shows the settings after file overrides; lsc check file.ts also checks dependencies.

Forwards to the bundled lemmascript-claimcheck CLI, which cross-examines the plain-English //@ contract line against the formal clauses. With a file, it checks that file (extra flags pass through verbatim); with no file, it runs once per entry in LemmaScript-files.txt.

Reads the run log and reports catches: failures that a later check or regen fixed, one per TypeScript function. Each is a source-fix (the .ts changed), a proof fix (only the .dfy changed) or flaky (nothing changed). A source fix also gets a hint at what the fix changed: code, spec (requires, ensures or contract lines), mixed, or proof (only invariants and other proof annotations). Failures not yet fixed are listed as open, or dropped if their function went away.

7 runs, 1 file, 2026-10-05 16:08 → 16:47
catches: 2 (source-fix 1, proof 1, flaky 0)
open: 0 dropped: 0
proof arraySum.ts arraySum failed 16:28, fixed 16:36
source-fix arraySum.ts arraySum failed 16:38, fixed 16:45 hint: code

The log is found as run-log above describes, or beside --config=<path>. Times are local. --json prints the full report, with UTC times and each source fix’s diff. The diff needs git; without it, source fixes have no diff or hint, and lsc runs prints a warning. lsc runs reads an existing log even when recording is turned off.

Run gen, gen-check, or check with no file argument to batch over LemmaScript-files.txt in the current directory — one entry per line:

src/domain.ts
src/allocate.ts 120
src/scanner.ts 300 --isolate-assertions

Format: filepath [timeout_in_seconds] [extra prover flags…]. Batching is fail-fast — the first failing entry stops the run.

By default, a Dafny check batch runs gen-check (generation + additions-only, no proving) for entries whose manifest timeout exceeds 60 seconds. Pass --slow to verify those entries with their manifest timeouts, or supply --time-limit to verify every entry with that timeout, even above 60 seconds.

CLI --time-limit and --extra-flags values override the corresponding manifest values independently. Omitted options retain each entry’s setting; an explicit --extra-flags= clears its flags. Repeating either flag is an error.

Terminal window
lsc check --backend=dafny --time-limit=120 # verify every entry with this limit
lsc check --backend=dafny --extra-flags="--isolate-assertions"
FlagApplies toMeaning
--backend=dafny|leanall except extract/infoBackend to target. Default: dafny
--config=<path>config-aware commandsPin lemmascript.json instead of nearest-ancestor discovery
--time-limit=<seconds>check, regenProver time limit (positive integer)
--extra-flags="…"check, regenExtra flags passed to the prover verbatim
--slowbatch checkVerify long-timeout entries instead of downgrading them
--no-verifyregenMerge + additions-only check only; skip the prover
DirectiveEffect
//@ backend <dafny|lean>The file belongs to one backend; commands for the other backend skip it (extract/info always run)
//@ option <key> <value>Override an eligible project option before the first source statement
//@ safe-sliceLegacy alias for //@ option safe-slice true
//@ lean-module <name>Overrides the Lean module base name (Lean module names are global; this prevents collisions between identically-named files)

lsc resolves imports using the nearest tsconfig.json and options using the nearest lemmascript.json above the source file. Without a TS config it falls back to strict ESNext defaults; without a LemmaScript config it uses backward- compatible option defaults. From a source checkout, the equivalent of lsc is npx tsx <checkout>/tools/src/lsc.ts — no build step needed.

For Lean checks, the nearest ancestor containing either lakefile.lean or lakefile.toml is the build directory. Discovery starts in the source directory and includes the filesystem root. A nearer TOML project takes precedence over an outer Lean project, and vice versa. If neither file is found, lsc check reports an error without starting Lake. A missing proof file also fails before Lake is started.