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.

Install

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

lantern --version

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 Get started.

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).

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": "<deployment-id>",
  "status": "live",
  "tenantId": "<tenant-id>",
  "url": "http://localhost:8080/v1/agents/demo-bot/a2a/invoke"
}

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)