CLI reference

One static Go binary. It boots the local stack, scaffolds and runs agents, gates CI on evals, drives sandbox VMs, and installs the data plane in your cloud.

Just looking? lantern demo needs Docker and no API key. To build your own, lantern dev boots the stack and lantern onboard walks you through your first agent.

Install

# Build from the repo
cd packages/cli && go install ./cmd/lantern
lantern --version

demo

Starts the self-contained demo (kiosk mode): Docker only, no API key. Each visitor gets a private workspace with sample agents that is deleted after 30 minutes; answers are recorded replays from a local fixture server. Run it from inside a PAL checkout. It builds and starts Postgres, Redis, the control plane, the dashboard and the replay server as the compose project lantern-demo, waits for /healthz and the demo page (up to 5 minutes), then opens http://localhost:3001/kiosk.

Flags: --no-open (don’t open the browser), --down (stop and delete all demo data). Host ports default to 8080 and 3001; override with KIOSK_API_PORT and KIOSK_WEB_PORT. See Demo.

lantern demo             # start (first run builds images)
lantern demo --no-open   # start without opening the browser
lantern demo --down      # stop and delete all demo data

onboard

First-run wizard: health check, sign-in, provider key (with a real test call), then the agentic part. It asks what you want the agent to do, the control plane designs it, you confirm, and the first run streams live. With --yes or a non-terminal stdin it never prompts (CI). Flags: --provider (openai|anthropic), --api-key, --description. See Quickstart.

lantern onboard                 # interactive
lantern onboard --yes --provider anthropic --api-key "$KEY" \
  --description "Triage support tickets"   # CI

doctor

Runs readiness checks against the local stack, one pass/fail line each. Exits non-zero if any hard check fails. Run it before you report a bug. The Sandbox runtime section, which never fails the run, reports whether the API uses a real scheduler or the stub, whether the scheduler and runtime manager are reachable, and whether KVM and Firecracker are present. Each failing check prints its fix.

lantern doctor

dev

Boots the local stack: Postgres, Redis and MinIO (Docker), the control-plane API (host Go process), the Next.js dashboard, and the WhatsApp and iMessage bridges (iMessage is skipped off macOS). Logs interleave in one terminal. Flags: --infra-only, --with-whatsapp=false, --with-imessage=false, --no-open, --dashboard-port (3001), --api-port (8080).

lantern dev                # start everything
lantern dev down           # stop infra containers (--volumes also deletes data)
lantern dev logs           # tail all infra logs
lantern dev logs postgres  # tail one service

init

Scaffold a new agent directory with agent.yaml and starter code. Templates: basic (default), research, tool-use, connector, personal, scheduled, approval.

lantern init my-agent
lantern init my-agent --template research

agents

Manage agents. Aliased as agent.

lantern agents create --name my-agent --description "Triage tickets" [--label team=support]
lantern agents list
lantern agents get my-agent
lantern agents delete my-agent [--force]

# Development inner loop — watches the agent dir and re-publishes on change
lantern agents dev my-agent [--dir ./my-agent] [--input '{"prompt":"hi"}'] [--eval] [--yes]

agents dev is the agent development inner loop: it watches the local directory for changes to agent.yaml or code files, re-publishes the agent version on each change, runs a smoke input (--input), and streams the run events. --eval also runs the agent’s eval suite after each publish.

runs

Manage runs: create, list, inspect, cancel.

lantern runs create --agent my-agent --input '{"topic":"AI"}' [--stream]
lantern runs list [--agent my-agent] [--status succeeded]
lantern runs get <run-id>
lantern runs cancel <run-id> [--reason "..."]

logs

Stream a run’s journal events. For dev-stack containers use lantern dev logs.

lantern logs <run-id> [-f]   # journal events; -f keeps the stream open

test

Run an agent’s eval suite and compare against the branch baseline. Exits non-zero with a regression summary when the score drops below the baseline. Wire it into CI to gate merges. --set-baseline pins the run as the branch baseline. --rehearse replays past failed or low-score production runs instead of a suite (--window, default 7d). Runs execute asynchronously on the control plane, so each case waits for its run to finish; --timeout (default 2m) bounds that wait per case, and a failed or timed-out run scores as a failed case with its error.

lantern test --agent my-agent --suite factual-accuracy
lantern test --agent my-agent --suite factual-accuracy --against last-green
lantern test --agent my-agent --rehearse --window 24h

vm

Schedule and manage headless sandbox VMs. lantern run takes a spec file; vm (aliases vms, runtime) manages what it started.

# Schedule a headless agent from a spec file
lantern run agent.yaml [--input '{...}'] [--follow] [--idle-timeout 600]

# VM subcommands
lantern vm list [--state running] [--limit 50]
lantern vm get <vm-id>
lantern vm logs <vm-id>          # SSE log stream from the harness
lantern vm stop <vm-id> [--grace 30]
lantern vm pause <vm-id>         # snapshot + stop, frees the quota slot
lantern vm resume <vm-id>        # restore under the same vm id
lantern vm fork <vm-id> --count 3   # N copies; the server caps N (100 by default, LANTERN_MAX_FORK_COUNT, ceiling 1000)
lantern vm exec <vm-id> -- ls /tmp  # exec into a running VM (-t/-i for a PTY)
lantern vm ls <vm-id> [path]     # list /workspace
lantern vm cat <vm-id> <path>    # print a file (1 MiB cap)
lantern vm put <vm-id> ./f.txt /workspace/f.txt   # write a file (1 MiB cap)
lantern vm quota get             # current quota + today's usage
lantern vm quota set --max-concurrent 10 --max-cost 50   # owner only
lantern vm cluster               # node load + warm-pool capacity (owner only)

deploy

Reads agent.yaml from the current directory, creates the agent on the control plane (or updates its system prompt and model if it already exists), saves the optional workflow graph, then calls POST /v1/agents/{name}/deploy. Manifest keys used: name (required), description, model, system_prompt, labels (set on create only; the update endpoint cannot change description or labels) and workflow. Other keys are ignored. Uses REST, so pass the HTTP address or let it derive one from the gRPC address.

Flags: --json (print the API response; same as -o json), --dry-run (one read-only lookup, reports create or update, changes nothing).

Exit codes: 0 ok, 3 unauthorized (401/403), 4 quota or budget (402), 5 not found (404), 6 server error (5xx), 1 anything else.

$ cat agent.yaml
name: demo-bot
description: demo
model: auto
system_prompt: You are terse.

$ lantern --api-url http://localhost:8080 deploy --json
{
  "agent": "created",
  "agentName": "demo-bot",
  "deployedAt": "...",
  "environment": "cloud",
  "id": "<agent-id>",
  "status": "live",
  "tenantId": "<tenant-id>",
  "url": "http://localhost:8080/v1/agents/demo-bot/a2a/invoke"
}

hooks

Manage inbound webhook triggers: a public POST /v1/hooks/{id} URL bound to an agent, so GitHub, Sentry, PagerDuty or any HMAC-signing sender starts a run. Aliased as hook and triggers. See Webhook triggers.

create prints the signing secret once; --secret-stdin reads one from stdin instead (Sentry and PagerDuty generate their own). --template maps the payload into run input. update needs at least one of its flags; --enable / --disable and --template / --clear-template are mutually exclusive, and a disabled trigger answers deliveries with 404.

lantern hooks create <agent> [--provider generic|github|sentry|pagerduty] [--template '{"pr":"{{payload.number}}"}'] [--secret-stdin]
lantern hooks list <agent>
lantern hooks get <trigger-id>
lantern hooks update <trigger-id> [--enable | --disable] [--template JSON | --clear-template] [--secret-stdin]
lantern hooks delete <trigger-id>

infra

Generate and manage the data plane for AWS, GCP or Azure (EKS, GKE, AKS) via Terraform.

lantern infra install --cloud aws [--region us-east-1] [--node-count 3] [--firecracker]
lantern infra status      # show connection status
lantern infra upgrade [--version latest]
lantern infra uninstall [--force]   # tear down the data plane

login / whoami / logout

lantern login [--email --password]   # authenticate to the control plane
lantern whoami                       # show current authenticated user
lantern logout                       # clear stored credentials

Global flags

--api-url string     Control plane address (default: $LANTERN_API_URL or localhost:50051, gRPC)
--api-key string     API key (default: $LANTERN_API_KEY)
--tenant-id string   Tenant ID (default: $LANTERN_TENANT_ID)
-o, --output string  Output format: text or json (default text)
--rest               Use REST instead of gRPC (or set LANTERN_USE_REST)