CLI Reference

The lantern CLI is a single static binary (Go + Cobra) that covers the entire development lifecycle: local dev, agent iteration, run inspection, headless VM management, and data-plane infra.

Install

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

lantern --version

onboard

First-run wizard: health check → auth → provider key → create agent → run. Gets you from a running stack to a working agent in under a minute.

lantern onboard

doctor

Runs a sequence of readiness checks against the local stack and prints a pass/fail line for each one. Exits non-zero if any hard check fails. Always run this before reporting a bug.

lantern doctor

dev

Boots the full Lantern stack locally with hot reload: Postgres, Redis, MinIO (via Docker), the control-plane API (host Go process), the Next.js dashboard, and the WhatsApp bridge. All logs interleave into one terminal.

lantern dev       # start everything
lantern down      # stop infra containers
lantern logs      # tail all infra logs
lantern logs api  # tail a specific service

init

Scaffold a new agent directory with agent.yaml and starter code.

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

agents

Manage agents. Aliased as agent.

lantern agents create --name my-agent --system-prompt "You are..."
lantern agents list
lantern agents get my-agent
lantern agents delete my-agent

# Development inner loop — watches the agent dir and re-publishes on change
lantern agents dev my-agent [--dir ./my-agent] [--run '{"key":"val"}']

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, and streams run events in the terminal.

runs

Manage runs (invoke, inspect, cancel). Aliased as run.

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>

logs

Tail logs for a run or a dev-stack service.

lantern logs <run-id>      # stream journal events for a run
lantern logs api           # dev-stack: tail the API service
lantern logs               # dev-stack: all services

test

Run an agent's eval suite and compare against the branch baseline. Returns non-zero (and prints a regression summary) when the score drops below the baseline — wire this into CI to gate merges.

lantern test --agent my-agent --suite factual-accuracy
lantern test --agent my-agent --suite factual-accuracy --against last-green

vm

Inspect and manage headless microVM agent runs. Aliased as vms and runtime.

# Schedule a headless agent from a spec file
lantern run agent.yaml [--follow]

# VM subcommands
lantern vm list [--state running]
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 exec <vm-id> -- ls /tmp   # exec into a running VM (debug)
lantern vm quota                 # current quota + today's usage
lantern vm cluster               # node load + warm-pool capacity (owner only)

deploy

Reads agent.yaml from the current directory, builds the agent bundle, uploads it, and deploys it to Lantern.

lantern deploy [--env staging]

infra

Manage the data plane in your cloud infrastructure (EKS, GKE, AKS).

lantern infra install   # generate Terraform config for the data plane
lantern infra status    # show connection status
lantern infra upgrade   # upgrade data plane components

login / whoami / logout

lantern login           # authenticate to the control plane
lantern whoami          # show current authenticated user
lantern logout          # clear stored credentials

Global flags

--api-url string    Control plane base URL (default: $LANTERN_API_URL or http://localhost:8080)
--api-key string    API key (default: $LANTERN_API_KEY)
--json              Output JSON instead of human-readable text
--no-color          Disable ANSI colour output
-v, --verbose       Verbose logging