CLI Reference

Every levee command and option, with examples and exit codes

levee.exe is Levee's command-line tool. It does from a PowerShell window what the desktop app does, which IT uses for scripts, monitoring, and remote support sessions. Most users never need it.

The Levee installer puts levee.exe in %ProgramFiles%\Vediram\Levee\bin\. That folder is not added to your PATH, so call it by full path, or add the folder to PATH yourself:

& "$env:ProgramFiles\Vediram\Levee\bin\levee.exe" doctor

Run levee --help, or levee <command> --help, for built-in help on any command.

Which command do I need?

The full reference follows.

Global options

These work with every command.

Exit codes

levee project exec is the exception: it returns the exit code of the command it ran inside the sandbox.

levee project start my-project
if ($LASTEXITCODE -ne 0) { Write-Error "Start failed with code $LASTEXITCODE" }

Health

levee doctor

Connects to the service and prints its health: service version and uptime, container engine status, images loaded, and any degraded subsystems. Exits with 1 if the service reports itself unhealthy, which makes it a convenient health probe for monitoring scripts.

levee doctor
levee doctor --json | ConvertFrom-Json

levee service start | stop | restart | status

Controls the LeveeService Windows service through the Service Control Manager. start, stop, and restart need an elevated PowerShell session.

levee service status
levee service restart

The container engine runs as a separate service, LeveeContainerEngine; manage it with the standard Windows tools (Get-Service LeveeContainerEngine, Restart-Service LeveeContainerEngine).

Projects

A project is a folder of work that the AI agent runs in, inside its own sandbox. Wherever a command takes <project>, you can pass the project's name, its 12-character id, or any unique prefix of the id. An ambiguous name or prefix fails with Ambiguous project name '...'.

levee project create quarterly-review
levee project start quarterly-review
levee project exec -p quarterly-review whoami
levee project attach -p quarterly-review
levee project stop quarterly-review

create has no path argument: projects are always created in the project directory you registered in the app (Settings > Workspace), which must be inside your own user profile. See Projects.

Only one project can run on a computer at a time. Stop the running project before you start another.

Common messages:

Container runtime

levee runtime status

Shows whether the container engine is installed and running, whether the sandbox image is present, and the state of any download in progress.

levee runtime ensure [--wait] [--timeout <seconds>]

Starts runtime provisioning now instead of waiting for the service's own schedule. Use it right after installation in a deployment script, or after placing an image in %ProgramData%\Vediram\Levee\images\ on an offline machine.

If the wait times out, the command returns code 5 and reports that provisioning continues in the background. If provisioning could not be started before the timeout, for example because the engine never came up, it also returns 5 and names the reason.

levee runtime ensure --wait --timeout 3600

See Container runtime, offline, and air-gapped.

Policy

levee policy show --json | ConvertFrom-Json | Select-Object -ExpandProperty proxies

If a policy file is invalid, the previous policy stays in force. See How policy works.

Audit

levee audit tail [--lines <n>] [--follow]

Prints the most recent audit events on this machine, oldest first. Standard users can run it: the audit files are readable without administrator rights.

With --json, each event is one compact JSON object per line.

levee audit tail --lines 200
levee audit tail --follow

If the audit database can't be read, the command prints one error, Cannot read the audit log at <path>: ... (a JSON error object with --json), and exits with 1. If the database doesn't exist, it prints Audit DB not found at <path> and exits with 4.

See Activity and audit.

Diagnostic logs

levee log tail

Reads Levee's diagnostic logs (distinct from the audit trail).

By default you see your own events and those of projects you own.

levee log tail --component service --level Warning --since 2h
levee log tail --component proxy.http --project 3f9c1a7e42b0 --follow
levee log tail --all --since 1d --json > levee-logs.json   # elevated

levee log status

Summarizes the log store: space used against the budget, the oldest data kept, per-component configuration state, and any recently dropped events.

See Logging.

Configuration

levee config validate [path]

Validates a logging configuration file without printing its values. With no path, validates the installed %ProgramData%\Vediram\Levee\config.json. Prints Valid. or Invalid. followed by diagnostic codes such as logging.invalid_default_level. Validate a candidate file before you deploy it:

levee config validate .\config.candidate.json

Package registry credentials (preview)

Stores the credential Levee uses to reach your company package registry for package access. The secret is read from standard input or a hidden prompt, never from the command line, so it doesn't appear in process-creation logs. set and clear require an elevated session.

# Prompted for the token without echo
levee upstream-auth set --manager npm --scheme bearer

# Or piped from a secret store
Get-Secret -Name ArtifactoryNpmToken -AsPlainText | levee upstream-auth set --manager npm --scheme bearer

Credentials are stored encrypted on the machine and are audited as UpstreamCredentialSet / UpstreamCredentialCleared (never with the secret).

Engine integrity

levee engine verify --manifest <file> --payload <folder>

Verifies the bundled container engine files against their SHA-256 manifest. The installer runs it automatically and rolls back if verification fails; you'd only run it by hand when asked by Vediram support.

Troubleshooting the CLI

Related

• Files and locations
• Collecting logs for support