CLI reference (lev)

Everything Leviath does is one binary, lev. This page lists every command and its flags. lev <command> --help prints the same thing at the terminal.

If a command is not doing what you expect, Troubleshooting is organised by symptom, and lev doctor checks the usual causes for you.

-v / --verbose is global and works on every subcommand.

Scripting against the CLI? --json is on run, ps, doctor, validate, list, models list, context, result, respond, stages, tools, approvals safe, and mcp list. Everything else prints for a person. Warnings go to stderr, so stdout parses on its own. A service that would rather speak HTTP should use lev serve instead.

Most commands talk to the shared-world daemon. lev run, lev dash, lev serve, and lev agent-client start one automatically if none is running, and restart it if it is running an older build.

Running agents

lev run [PATH]

Spawn an agent into the daemon. PATH is an installed agent name, a blueprint directory, or an agent.leviath file. Omitted, the current directory is used.

--workdir decides more than where commands run. File tools are confined to it, and relative [read_paths] entries resolve against it.

--json is for a caller that parses the run id back out. With --count above 1 it prints an array, one object per run.

--yolo waives approvals, not checkpoints. It approves every tool call, and it takes away the tools that wait on a person (ask_user_*, present_for_review, edit_document) so the run does not stop for somebody who is not there.

Two things still hold it. A stage keeps whatever it lists in required_tools, and an interaction point declaring unattended = "ask" opens its prompt however the run was launched. A blueprint can ask for that on its plan approval, because everything after that gate writes code. lev run --yolo prints what will hold before the run starts, and lev validate reports it as holds-under-yolo.

--yolo can turn an ask into an allow, but it can never lift a deny.

Region seed flags are dynamic, because region names come from the blueprint. Any --<name> that is not one of the flags above is read as a seed for the region called <name>, and a value starting with @ is read from that file:

lev run reviewer --task "Review the auth module" --standards @./team-standards.md

A region only accepts a seed if the blueprint declares it as caller input: a string seed = "<key>" in its [context.regions] entry, or being named task, which asks for the task key implicitly. A table seed (seed = { glob = ... }, { command = ... }, and so on) fills the region from somewhere else and takes no caller input. A --<name> naming any other region is dropped.

Writing the task in your editor

Run lev run <agent> with no -t and Leviath opens your editor on a short commented template. Type the task, save, and the run starts. Lines beginning with # are stripped, so none of the template reaches the agent. Save an empty file and the run is cancelled.

The editor is $VISUAL, then $EDITOR, then the first of vim, nano, vi that is installed. On Windows it is edit, then notepad, then vim. $VISUAL and $EDITOR are split on whitespace, so code --wait works, but a program path containing spaces needs a wrapper script on your PATH.

Stdin has to be a terminal for any of this. In a script, a pipeline, or CI, pass -t and Leviath says so rather than blocking.

-t reads a file when the value names one that exists. A value that looks like a path with no file behind it is an error, so a mistyped filename fails instead of quietly becoming the prompt. "Looks like a path" means no spaces, plus a /, a \, or a leading ~. Region flags work the other way round and want an explicit @ before a path, because a region seed is usually a file while a task is usually a sentence.

lev stages <RUN-ID>

The per-stage token ledger, which is where a staged agent's cost lives. A single loop has one number you can eyeball; a staged agent has a different window per stage, regions that persist across stages, and per-stage models with different prices.

STAGE                STATUS         PROMPT     OUTPUT   CACHE RD   CACHE WR
ingest               complete        16832       2249          0          0
report               complete        37644        493          0          0
summary              complete       252848        648          0          0
TOTAL                               307324       3390          0          0

CACHE WR is the write half of a cache decision. Without it a stage showing no reads might be paying to write a prefix nothing reuses, or might not be caching at all, and the ledger could not tell those apart.

--regions answers the question a structured layout is really asking: what am I paying to carry, and where. The number shown is the largest each region reached while the stage was active, since a region is re-sent whole on every call.

Leviath also warns once when a stage's per-call prompt grows past four times its first call. That is the shape of a region accumulating without a cap, which is the failure that costs money and the hardest one to spot by eye.

lev create <NAME>

Scaffold a new blueprint directory.

lev validate [PATH]

Check a blueprint before running it. PATH defaults to ..

Beyond parsing and structural validation, it reports what the blueprint leaves unsaid. Findings come in three levels: an error exits non-zero, a warning does not, and a note never does.

Thirteen of those findings need more than a phrase.

unknown-tool means the name matches no built-in, no sub-agent tool, and no tools/*.rhai file. The stage then advertises one tool fewer, so the model is told a tool it was meant to have does not exist. MCP names (server__tool) are skipped, since they resolve only once that server is installed.

unparseable-safe-command fires on an entry that is not a bare command prefix, so no call can ever match it. Write a program, optionally with the subcommand that narrows it: rg, cargo test.

output-missing-submit-tool means a stage sets require_output but never grants submit_output. Use mode = "output", which grants the tool.

region-seed-not-understood is usually a typo in a table key. It is { caller = "task" }, not { caller_input = "task" }. An unrecognized seed is ignored, and the region starts empty.

blocking-tool-in-autonomous-stage fires when an autonomous stage grants ask_user_*, present_for_review or edit_document. With nobody attached, the run parks there until it is killed. Set allow_blocking_tools = true on the stage to say you meant it.

implicit-shell-policy matters because the default is ask. An unattended run waits on that prompt rather than being denied.

unknown-model is checked only against providers with a closed catalog. Ollama, OpenRouter and script providers are never checked.

compact-summarizes-deliverable means a later stage reads a paraphrase of a region you marked required. Set summarizable = false on the region.

dead-end-possible fires when every normal edge's target has a max_revisits budget, so the run errors once they are spent. Add a condition = "dead_end" edge to a stage without one. A max_iterations edge does not count, because it fires on the iteration cap rather than on this path.

read-paths-not-granted is the declaring-is-not-granting case. Those reads are refused at runtime, and the fix line carries the stanza that would grant them.

holds-under-yolo names an interaction point declaring unattended = "ask", or a blocking tool a stage keeps in required_tools. Both are deliberate wherever they appear. It is a note because --yolo reads as "run without me".

safe-commands-declared applies only where you opt in. That is per agent via [agent_safe_commands.<name>] allow_blueprint, or globally via [security] allow_blueprint_safe_commands.

command-seed and read-paths-declared say what the blueprint will do before you run it. read-paths-declared carries the granted and declared counts, plus each entry's status.

The same findings are written to daemon.log when a run spawns, so a blueprint that was never validated still says what is wrong with it. Nothing there refuses a spawn.

[read_paths] entries are checked against your own config.toml, entry by entry, because declaring one is not the same as being allowed to read it. Anything your config does not grant is named as such, with the stanza that would grant it. The daemon's own lint has no user config to consult, so there it stays the plain "these need granting" note. See reading outside the workdir.

lev test [PATH]

Run a blueprint's tests: everything in its tests/ directory, against the real provider.

Each tests/*.toml file holds one or more cases:

[[test]]
name = "greeting"
input = "Say hello"
expect_contains = "hello"

[[test]]
name = "reads the config"
input = "What is in config.toml?"
expect_tool_call = "read_file"
max_tokens = 500

What a case actually runs. One inference, not a run. lev test builds a fresh context window from the blueprint's layout, seeds input as the task, and assembles the request exactly as a live run's first turn would. That means iteration 0, region hooks active, and the first stage's model and tools. It then calls the provider once and checks the assertions. Nothing executes: a tool call is asserted on, never performed, so a case can expect write_file without a file appearing.

A tests/*.rhai file is run instead as a script through the scripting engine, and fails the run if it returns false.

lev models

lev agent-client

Serve an agent over the Agent Client Protocol as JSON-RPC on stdio.

Blueprints and packaging

lev list --filter narrows the listing to installed agents or to bundled blueprints. An unrecognized value is an error rather than a silent ignore. An agent declaring [read_paths] also shows how many of its entries your config grants.

Watching and steering

lev cancel --force writes the run's on-disk state terminal without asking the daemon, for when the daemon is gone or unresponsive. Without it, the daemon is asked first, since it can stop the work rather than only record the outcome, and the on-disk write is the fallback.

lev context --full includes each region's entry contents instead of per-region summaries.

lev result

Print the answer a finished run submitted. It reads the run's meta.json, so it needs no daemon and works for a run that finished last week.

lev result agent-abc123          # the answer, with its run and stage
lev result agent-abc123 --raw    # the answer alone, for a pipeline
lev result agent-abc123 --json   # the answer plus its shape and stage

A run that produced no answer exits non-zero rather than printing nothing. So lev result <id> > answer.txt in a script cannot quietly write an empty file.

Files the run produced are listed under the answer. Fetch one however you normally would; the paths are relative to the run's working directory.

Only an agent that calls submit_output has an answer to show. See Final outputs for how a blueprint asks for one.

lev respond [REQUEST_ID] [VALUE]

Answer an interaction the daemon is holding. With no REQUEST_ID, lists the open ones.

See Human-in-the-loop for what raises these.

Reading lev ps

RUN                             TITLE                  STATUS                  STAGE         ITER   TOOLS  AGE
solo-1785568852-9fa61fd279dd    Retry backoff audit    waiting: tool approval  work          1      1      41s
busy-1785568852-384bad04c9ac    Index the changelog    active                  work          13824  13824  0s
waiter-1785568852-7895a2209850  Split the log sweep    waiting: children(1)    delegate 1/2  2      1      41s

1 run needs an answer: lev respond

TITLE is the generated one-line title, and the column appears only when at least one listed run has one - a run whose titling was turned off or did not finish leaves the cell empty rather than widening every row for nothing.

AGE is how long since the run last moved: a new iteration, a new stage, or a change of status. It is deliberately not meta.json's updated_at, which also advances on a 30-second heartbeat so that observers can tell a live daemon from a dead one. A fresh updated_at is therefore not evidence of progress; a fresh AGE is. The same figure is written to disk as last_progress_at, so a script can read it without the daemon.

lev ps lists what the daemon is holding, plus the runs that finished within the retention window above. lev ps --all adds a second block read from the runs dir instead, so runs older than that window, and runs from before the last daemon restart, are still accounted for:

NOT RUNNING
RUN                             STATUS               LAST MOVED
coder-1785568100-a1b2c3d4e5f6   complete             4m
coder-1785567000-c3d4e5f6a1b2   error                1h
router-1785560000-e5f6a1b2c3d4  running (abandoned)  2h

(abandoned) means the run claims on disk to be running, the daemon is not holding it, and it has not moved in five minutes. Clear it with lev cancel <run-id>. With --all a daemon that is down is reported rather than fatal, and nothing is marked abandoned in that case, because an unreachable daemon looks exactly like every run dying at once. See reconciling an external work queue if you are driving Leviath from a scheduler.

A waiting run always says what it is blocked on, because the answer decides whether you need to do anything. These are stopped until a person acts:

These resolve on their own, and are a normal part of a healthy multi-agent run:

That distinction is the useful one. waiting: children(3) next to three busy children is a healthy run doing exactly what it should. waiting: tool approval at ten minutes is a run nobody answered.

Launch with --yolo to approve automatically. Sub-agents and fan-out workers inherit it, and it survives a daemon restart.

(no output)

A finished run can read complete (no output), and likewise for cancelled and error. It means the run changed no files, even though its agent had a tool for changing them.

Almost always the edits went through the shell, which Leviath cannot see. sed -i, tee, and redirects leave no trace, so nothing downstream knows the work happened. Either re-apply those edits with write_file or edit_file, or name the tool you do write with in a transition gate so that it counts.

Agents that never had a file-writing tool are never marked this way. A router that delegates, or a researcher whose answer is its report, has no file changes to be missing.

The READS column

This column only appears when one of the listed runs declares [read_paths]. It reads granted over declared, as resolved when the run spawned.

0/2 is the one to watch for. That run is up and looks healthy, and every read its author designed it around will be refused. Run lev validate <agent> to see which entries, and the config block that grants them.

Runs that have finished

A run keeps its place in the listing for five minutes after it ends, then drops out.

That window exists so a run that failed is still there to say so. Without it, a run that died on its first model call would leave the listing within seconds, and read exactly like a run that was never spawned at all.

So you get this instead of an empty listing:

RUN                             STATUS                              STAGE  ITER  TOOLS  AGE
worker-1785616492-6f0d21ab4c11  error: HTTP 402 Payment Required    work   0     0      41s

ITER 0 and TOOLS 0 next to an error mean the run never got as far as its first turn. Set [limits] finished_retention_secs to widen or narrow the window, or 0 to drop a run as soon as it finishes. The record is held in memory, so restarting the daemon clears it early; the durable copy is the run's meta.json, which GET /api/agents reads.

Two things this does not cover. A spawn that fails outright never becomes a run, so it is reported by lev run itself rather than here. And a run that finished longer ago than the window is gone from the listing for good.

lev ps --json prints the same data unformatted, for scripts:

{ "runs": [ ... ], "finished": [ ... ], "health": { ... } }

Finished runs are their own key rather than mixed into runs, so counting what is running stays a matter of reading one list. Both carry the empty_output field, and a read_paths object with the granted and declared counts when the blueprint declares any. The completion webhook carries the empty_output key.

The daemon and API

lev daemon [ACTION]

With no action, runs the daemon in the foreground.

--socket <ID> overrides the control socket path and works on every action.

lev serve

Start the REST and WebSocket API.

Configuration and tools

lev doctor

Check that provider wiring works, end to end. Four checks run in order, the first failure stops the rest, and the one that fails is the diagnosis.

$ lev doctor

  config     OK  default_provider=openrouter; registered: ollama, openrouter (script providers resolve by name)
  resolve    OK  openrouter / anthropic/claude-sonnet-4.5
  inference  OK  12 in / 4 out / 16 total, replied PONG  (1.2s)
  daemon     OK  run doctor-1785649252-bf7b3d07a265 Complete after 1 iteration(s)  (0.3s)

doctor passed

The fourth check spawns a throwaway one-stage agent with no tools, waits for it, and then deletes the run. Nothing is left in lev ps or on disk.

--model takes provider/model to pick both, and a bare model id pairs with your default_provider. --model provider/model is the way to reach a Rhai script provider, which is resolved by name and so cannot be listed. Use it to try a model string before wiring it into a blueprint.

lev doctor exits non-zero when a check fails, so it works as a CI gate. It bills two inferences per run, each capped at 64 output tokens; --no-daemon bills one.

lev setup

The interactive provider wizard. Every credential and agent choice it asks for has a flag, so headless setup is scriptable. The wizard's Limits screen edits the [limits] keys, which have no flags: script those by writing config.toml directly. That screen is opt-in - every limit already has a working default, so it only appears once you turn on Show advanced tuning on the Defaults screen. Skipping it changes nothing about what gets written.

lev setup --non-interactive --anthropic-key sk-ant-... --install-agents

Each blueprint is listed with what setup would do to it: install it, update it from the version on disk, or nothing. A copy at the bundled version whose files differ from the bundled ones reads as edited locally and is offered unchecked, because installing removes the destination directory first and would take your edits with it.

lev run says the same thing at the moment it matters: a run starting on an installed bundled blueprint that this build ships a different version of prints a one-line note before it spawns.

Inside the wizard, the keys work the same way on every screen:

Nothing is written until you confirm on the Review screen. Leaving the provider screen with nothing selected asks before letting you continue, since an agent cannot run without one.

lev mcp

Manage MCP tool servers.

Transport is inferred from whether you pass --url or --command.

lev auth

lev auth migrate moves keys into the OS store by default; --to-file moves them back out. Set [security] credential_store in the config first.

lev update

Update Leviath, then offer to bring everything else up to date with it: the binary, the bundled blueprints, and the config file, in that order.

The binary is updated with the installer that put it there, and which one that was is read off the filesystem rather than guessed from the version string. The version cannot answer: every channel ships the same number, because the -alpha and -beta suffixes live in the tap manifests and not in the binary. Where the file sits does answer.

A Cellar or apps path carries the package name, and the package name carries the channel, so a beta install updates to beta without being told. The install script records nothing at all, so its channel is genuinely unknowable: that arm defaults to stable and --channel is how you say otherwise.

A cargo install is described rather than run, because updating it is a full compile and that is not something to start because somebody typed lev update.

$ lev update --check

lev 0.3.5, installed with Homebrew (formula leviath-beta, beta channel)

  binary   brew upgrade leviath-beta
  agents   1 of 7 would change
             data-analyst - update 0.0.1 → 0.0.2
  config   nothing to migrate

All three steps run every time, whatever the binary step did. That is the point of the command: brew upgrade and scoop update hand you a new binary and say nothing about the blueprints in ~/.leviath/agents or the config beside them, so anyone who has ever updated that way is running blueprints from whenever they last ran lev setup. A binary that needs no update is not evidence that anything else is current.

The blueprint step is the same offer lev setup makes, and nothing is written to your agents directory without a yes. The whole list is printed first, then one confirmation covers it; --install-agents is how a script says yes. --yes alone is deliberately not enough, because updating a binary and replacing the blueprints in your agents directory are different requests.

A copy at the bundled version whose files differ from the bundled ones reads as edited locally. It is named as edited, asked about on its own, and no flag covers it: installing removes the destination directory first and would take your edits, and any file you added, with it.

The config step applies any migration this build knows how to make, printing every change before it asks to write anything. Today there are none: no released config.toml has to change to work with this version, so the step exists to explain a future one rather than to do work now.

lev tools

Lists and validates the global Rhai tool scripts in ~/.leviath/tools/.

lev approvals safe

Print what runs without an approval prompt, and which file put each entry there. This is the answer to "why did it not ask me".

There is no list or clear: nothing is persisted. A grant made at a prompt dies with the run that made it, so the only durable state is the config this reports. See Human-in-the-loop for what the entries mean.

lev policy

Manage taint tracking policy rules.

Environment

LEVIATH_HOME redirects the whole data root, and LEVIATH_CONFIG_PATH points at an exact config file. Those two plus the rest are in the configuration reference.

Examples on this page use Unix shell syntax. On Windows, set variables the way your shell does:

$env:LEVIATH_HOME = "D:\leviath"          # PowerShell

set LEVIATH_HOME=D:\leviath

The per-command Unix prefix form (LEVIATH_HOME=/tmp/lev lev ps) has no direct equivalent; set the variable first, then run the command.