Reference
Command reference
Every command, its options and its exit status. lev COMMAND --help prints the same options.
Global options
| Option | Meaning |
|---|---|
--project PATH | Start project discovery from PATH instead of the current directory. The nearest directory with a lean-toolchain file is the project. |
--cache-dir PATH | Use this cache directory instead of LEV_CACHE_DIR or the platform default. |
-q, --quiet | Suppress lev's informational output and the Lake build output it relays. lev check still prints the output of a build that fails. |
-v, --verbose | Show the commands lev runs and the caches it reads. |
lev inspect build
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
lev check [--kernel official|paranoid|nanoda]... [--jobs N] [--no-build] [--no-sandbox]
[--json] [--only MODULE]... [--timeout SECS]| Option | Meaning |
|---|---|
--kernel K | A kernel that must accept every module: official (leanchecker, the default), paranoid (leanchecker-paranoid) or nanoda (nanoda_bin). Repeat for several. |
--jobs N | Exporter threads and parallel kernel runs. Default: the number of CPUs, at most 16. |
--no-build | Check the current build instead of running lake build first. |
--no-sandbox | Run Lake's queries, the exporter and the kernels without bwrap. |
--json | Print the lev.cli.check/v2 report. |
--only MODULE | Check only this module and what its slice relies on: its imports and the owners of the constants it uses. Repeatable. |
--timeout SECS | Time 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
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
lev cache gc [--max-age-days N] [--lake] [--apply] [--json]| Option | Meaning |
|---|---|
--max-age-days N | Keep entries used or written within the last N days. Default 30. |
--lake | Also 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. |
--apply | Delete exactly the listed entries. |
--json | Print 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
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:
| Command | Schema |
|---|---|
lev inspect build --json | lev.cli.inspect.build/v2 |
lev check --json | lev.cli.check/v2 |
lev cache status --json | lev.cli.cache.status/v2 |
lev cache gc --json | lev.cli.cache.gc/v2 |
lev doctor --json | lev.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
| Variable | Effect |
|---|---|
LEV_CACHE_DIR | lev's cache directory, unless --cache-dir is given. |
LEV_ELAN, LEV_GIT | The elan and Git executables lev runs. Default: elan and git on PATH. |
LAKE_CACHE_DIR | Read, never set: where Lake keeps its artifact cache, as Lake decides it. |
XDG_CACHE_HOME | The parent of the default cache directory on every platform when set. |
PATH | Where lev finds elan, Git and bwrap. lev check passes it into the sandbox so that Lake finds Git. |