lev docs

Global options

OptionMeaning
--project PATHStart project discovery from PATH instead of the current directory. The nearest directory with a lean-toolchain file is the project.
--cache-dir PATHUse this cache directory instead of LEV_CACHE_DIR or the platform default.
-q, --quietSuppress lev's informational output and the Lake build output it relays. lev check still prints the output of a build that fails.
-v, --verboseShow the commands lev runs and the caches it reads.

lev inspect build

Synopsis
lev inspect build [--json] [--why MODULE] [-- LAKE_ARGS...]

Runs lake --verbose build LAKE_ARGS through elan and explains from Lake's traces why each module rebuilt. --why MODULE follows one module's causes back to the module that rebuilt for its own reasons. Exit status: Lake's. Inspection

lev check

Synopsis
lev check [--kernel official|paranoid|nanoda]... [--jobs N] [--no-build] [--no-sandbox]
          [--json] [--only MODULE]... [--timeout SECS]
OptionMeaning
--kernel KA kernel that must accept every module: official (leanchecker, the default), paranoid (leanchecker-paranoid) or nanoda (nanoda_bin). Repeat for several.
--jobs NExporter threads and parallel kernel runs. Default: the number of CPUs, at most 16.
--no-buildCheck the current build instead of running lake build first.
--no-sandboxRun Lake's queries, the exporter and the kernels without bwrap.
--jsonPrint the lev.cli.check/v2 report.
--only MODULECheck only this module and what its slice relies on: its imports and the owners of the constants it uses. Repeatable.
--timeout SECSTime limit of one kernel run. Default 3600. A run that exceeds it is an error and is not cached, and the module counts as not checked.

Exit status: 0 accepted. 1 rejected: a kernel rejected a slice in every view, or a linker rule failed. 2 not checked: lev could not set the check up, or a kernel run ended in an error, a timeout or a decline and nothing was rejected. The verdict in the report is then unknown, and check.unchecked names the modules. Checking

lev cache status

Synopsis
lev cache status [--json]

Inventories lev's cache, the caches of lev check, and the Lake caches of registered projects. Exit status: 1 when a local Lake mapping names a missing artifact, 0 otherwise. Cache

lev cache gc

Synopsis
lev cache gc [--max-age-days N] [--lake] [--apply] [--json]
OptionMeaning
--max-age-days NKeep entries used or written within the last N days. Default 30.
--lakeAlso collect the Lake artifact caches of registered projects: mappings and artifacts that no registered project's traces reference. Without it, only lev's own cache is collected.
--applyDelete exactly the listed entries.
--jsonPrint the lev.cli.cache.gc/v2 report.

Lists the entries that nothing uses any more and that are older than the gate. A Lake cache whose references lev cannot read in full is skipped with the reason, and one that projects lev has not registered may use is listed as shared. Exit status: 0. Cache

lev doctor

Synopsis
lev doctor [--json]

Reports elan, Lean and Lake for the project's toolchain, Git, bwrap, the kernel binaries in the toolchain, what lev check has built for the toolchain, where Lake's artifact cache lives and whether it shares the project's filesystem, and lev's cache directory, followed by the problems these facts reveal. Outside a project it reports only the machine. Exit status: 0.

JSON output

Every --json command prints one object on stdout, {"schema": ..., "data": ...}, and nothing else. The schema string names the command and the version of its data:

CommandSchema
lev inspect build --jsonlev.cli.inspect.build/v2
lev check --jsonlev.cli.check/v2
lev cache status --jsonlev.cli.cache.status/v2
lev cache gc --jsonlev.cli.cache.gc/v2
lev doctor --jsonlev.cli.doctor/v2

The envelope is described by schemas/cli-envelope-v1.schema.json. Branch on the schema string before reading the data. Progress and errors go to stderr, so stdout stays one complete document, and a command that fails before it has a report prints no JSON.

Environment

VariableEffect
LEV_CACHE_DIRlev's cache directory, unless --cache-dir is given.
LEV_ELAN, LEV_GITThe elan and Git executables lev runs. Default: elan and git on PATH.
LAKE_CACHE_DIRRead, never set: where Lake keeps its artifact cache, as Lake decides it.
XDG_CACHE_HOMEThe parent of the default cache directory on every platform when set.
PATHWhere lev finds elan, Git and bwrap. lev check passes it into the sandbox so that Lake finds Git.