CLI reference

lean <command> [options]

Run lean --help or lean <command> --help for the same information from the binary itself.

The model argument

Most commands take a <model> argument, which is either:

• a model name (lean-agent-light), resolved against ~/.leanmodels/models/<name>/, or
• a path to a directory containing a manifest.json.

A model whose download was interrupted is rejected with a message telling you to resume it with lean pull.

Running models

lean run

Interactive chat REPL with multi-turn history.

lean run lean-agent-light --temperature 0.3

Flag	Default	Description
--max-tokens <n>	2048	Maximum tokens generated per response.
--system <text>	none	System prompt for the session.
--temperature <f>	0.7	Sampling temperature. 0 is greedy.
--gpu <n>	auto	Pin to one GPU by ordinal.
--pipeline	off	Split layers across all GPUs instead of using one.
--no-think	off	Skip the <think> phase on models that support it.

In-REPL commands: /stats for cache and throughput numbers, /clear to reset the conversation.

lean serve

Start an OpenAI-compatible HTTP server. See the API reference for endpoints and payloads.

lean serve lean-agent-light --port 8080

Flag	Default	Description
--host <addr>	127.0.0.1	Bind address. Use 0.0.0.0 to expose on your network.
--port <n>	8080	Listen port.
--gpu <n>	auto	Pin to one GPU by ordinal.
--pipeline	off	Split layers across all GPUs.
--api-key <key>	none	Require Authorization: Bearer <key> on /v1 routes. Also read from LEAN_API_KEY.
--request-timeout-secs <n>	600	Abort a generation after this long. 0 disables the timeout.

Binding to a non-loopback address without an API key logs a warning: anyone who can reach the port gets unauthenticated inference.

Single-GPU vs pipeline

By default the runtime uses one GPU when the model fits on it, because batch-1 decoding gains nothing from pipeline parallelism - the GPUs just run sequentially with a hidden-state hop between them each token. --pipeline forces the split across all cards, which helps when a model’s expert working set is too large to cache well on a single card. --gpu <n> and --pipeline are mutually exclusive.

Getting models

lean pull

Download a model from the registry. Resumable, checksum-verified, and it checks free disk before starting.

lean pull lean-agent-light

Flag	Default	Description
--registry <url>	https://registry.leanmodels.ai	Registry to pull from. Also read from LEAN_REGISTRY_URL.
--minimal	off	Fetch the core plus hot experts only, skipping cold experts.
--output <dir>	~/.leanmodels/models/<model>	Where to write the model.

--minimal gets you a working model sooner and on less disk; cold experts are the ones routing rarely selects, so quality degrades only on the inputs that need them.

lean login / lean logout

Paid models require an API key.

lean login              # prompts for the key
lean login --api-key lm_live_...
lean logout             # removes stored credentials

Flag	Description
--api-key <key>	Supply the key non-interactively.
--registry <url>	Registry to authenticate against.
--no-verify	Store the key without checking it against the registry first.

lean models

List locally installed models, or the registry catalog with --remote.

lean models
lean models --remote

lean verify

Walk every checksum in a model’s manifest and report damaged or missing files. Damaged models are marked so the next lean pull repairs them.

lean verify lean-agent-middle

Inspecting and measuring

lean info

Print a model’s manifest: architecture, parameter counts, expert layout, quant, and hardware requirements.

lean info lean-agent-light

lean tune

Detect hardware and recommend models and settings. Takes no arguments.

lean tune

lean bench

Measure prefill and decode throughput, cache hit rates, and memory use.

lean bench lean-agent-light

Flag	Default	Description
--gpu <n>	auto	Pin to one GPU by ordinal.
--pipeline	off	Split layers across all GPUs.
--ram-budget <mb>	auto	Cap the host-side expert staging budget.
--timed	off	Print a per-layer timing breakdown.
--runs <n>	3	Repeat each phase this many times and report median plus min/max.

Lowering --ram-budget is the way to simulate a machine with less RAM than yours without actually having one.

lean smoke

Run a fixed set of diverse prompts to sanity-check output quality after an install, a pull, or a hardware change.

lean smoke lean-agent-light --verbose

Flag	Description
--gpu <n>	Pin to one GPU by ordinal.
--pipeline	Split layers across all GPUs.
--verbose	Print the generated output for each prompt.

Environment variables

Variable	Effect
LEAN_REGISTRY_URL	Default registry for pull, login, and models --remote.
LEAN_API_KEY	API key required by lean serve on /v1 routes.
RUST_LOG	Log filter. Defaults to info; RUST_LOG=debug for more detail.