CLI

lastlight is a thin client for a running Last Light instance. It doesn't run agents itself — it authenticates once, then POSTs triggers and reads the instance's admin API over HTTP. That makes it the primary way to drive and debug an instance (including production) without SSHing to the host.

Connecting

lastlight login opens your browser to authenticate against the instance (password, Slack, or GitHub — whatever that instance has enabled) and saves the token to ~/.lastlight/config.json. Every later command runs against that saved instance.

lastlight login                       # prompts for the instance URL
lastlight login https://ll.example.com
lastlight login https://ll.example.com --password   # headless fallback (no browser)
lastlight logout                      # forget the saved instance + token
lastlight status                      # instance URL, server health, token validity

Target resolution for every command, highest priority first: --url / --token flags → LASTLIGHT_URL / LASTLIGHT_TOKEN env vars → the saved ~/.lastlight/config.json → http://localhost:8644. So env vars override the saved file, which lets CI and scripts target a different instance without touching disk.

Chat

Chat with the bot from your terminal — the same in-process chat skill that answers Slack threads, no messaging platform required. With a message it's one-shot; with no message it opens an interactive REPL (type exit to quit). Each conversation is a stable thread, so context carries across turns, and the turn shows up in the dashboard Chat tab tagged cli.

lastlight chat "what does the build workflow do?"
lastlight chat                        # interactive REPL

Triggering work

Point the CLI at a GitHub issue or PR. A bare reference is the cheap default (triage an issue / review a PR); a full build cycle is always an explicit opt-in via build.

lastlight <github-url>                 # default: triage that issue
lastlight owner/repo#42               # shorthand for the same
lastlight build owner/repo#42         # FULL build cycle (architect → executor → reviewer → PR)
lastlight triage owner/repo           # scan a repo for issues to triage
lastlight triage owner/repo#42        # triage one issue
lastlight review owner/repo           # scan a repo's PRs to review
lastlight review owner/repo#99        # review one PR
lastlight verify owner/repo#42 -- "the rate limiter blocks"   # test a claim → CONFIRMED/REFUTED
lastlight qa-test owner/repo#42 -- "login, create a project"  # drive a flow → step pass/fail
lastlight health owner/repo           # weekly health report
lastlight security owner/repo         # security review

Debugging a running instance

These read the same data the dashboard shows, so you can investigate a remote instance from the terminal instead of SSHing in. Add --json to any of them for machine-parseable output (pipe into jq). Where an id is omitted, the CLI fetches the relevant list and lets you pick interactively.

Workflow runs

lastlight workflow list [--status failed] [--workflow pr-review] [--limit 20]
lastlight workflow log <run-id> [--follow]    # phases + per-phase status; --follow tails live

Agent sessions

lastlight session list [--limit 30]
lastlight session log <session-id> [--follow] [--since N] [--full]

session log renders the transcript like the dashboard timeline — tool calls paired with one-line result summaries. --follow streams it live; --full dumps the raw, unformatted transcript.

Log search

lastlight logs search "ECONNREFUSED"                   # search execution errors (default)
lastlight logs search "rate limit" --scope all         # errors + transcript content
lastlight logs search "could not clone" --scope messages --limit 20

Server / container logs

Read the raw docker logs of the instance's containers (the agent harness plus the egress sidecars) over the API — for crashes before any session was written, or a misbehaving sidecar.

lastlight server list                                  # the lastlight-* containers + status
lastlight server logs                                  # the agent harness (default)
lastlight server logs --tail 500 --since 10m --follow
lastlight server logs coredns-strict                   # a specific service/container

Approvals & stats

lastlight approvals list                               # pending approval gates
lastlight approvals approve <id> [--reason "..."]
lastlight approvals reject  <id> [--reason "..."]
lastlight stats                                        # totals + per-skill success/fail
lastlight stats --daily 14                             # cost / token rollups

Server lifecycle (host-local)

Unlike the commands above (which target a remote instance over HTTP), these run on the server: they shell out to git and docker compose in a working directory (a full repo checkout + the instance/ overlay + the compose override symlink). The working dir resolves from --home → LASTLIGHT_HOME → the saved serverHome → ~/lastlight.

lastlight server setup                # scaffold/adopt the working dir (clone core + overlay)
lastlight server start [service]      # docker compose up -d
lastlight server stop  [service]      # stop one service, or the whole stack (down)
lastlight server restart [service]    # restart a service (default: agent)
lastlight server update               # pull core + overlay, build, recreate, restart sidecars, health-check
lastlight server status               # compose state + core/overlay version drift + forked-asset overrides

server update is the CLI equivalent of the production deploy.sh; it accepts --no-core, --no-overlay, --no-build, and --yes. The dashboard shows an "update available" banner when the running instance is behind the latest core or overlay.

Forking built-in assets

The instance/ overlay can override any built-in workflow, prompt, skill, or persona file — it wins by logical name at startup. lastlight fork (host-local) copies the built-ins you want to customise into the overlay so you can edit them per-deployment, instead of hand-copying files.

lastlight fork                        # list forkable workflows + agent-context (marks what's forked)
lastlight fork <workflow>              # copy a workflow YAML + every prompt & skill its phases reference
lastlight fork agent-context [file]   # copy soul.md / rules.md / security.md (all, or one named file)

It writes into the overlay resolved from --home (else the cwd if it's an overlay or checkout, else the server home); pass --force to overwrite assets already present. Forked assets then show up as overrides — in lastlight server status and in the dashboard's Config → Overrides pane — each tagged "shadows default" or "added".

Claude Code skills

Last Light ships a Claude Code plugin that teaches Claude Code to install, configure and operate Last Light and Last Light Evals — ask it e.g. "set up a Last Light server" or "scaffold an evals workspace". lastlight skills install (host-local) installs the bundled, version-matched skills: it uses the claude plugin marketplace when present, otherwise copies the skills into ~/.claude/skills.

lastlight skills install              # → ~/.claude/skills (user) [--scope project] [--no-marketplace]
lastlight skills list                 # bundled skills + where they're installed
lastlight skills uninstall            # remove them [--scope user|project]

The bundle includes lastlight-server, lastlight-client, lastlight-overlay and lastlight-evals. You can also register the marketplace directly from a checkout: claude plugin marketplace add ./ then claude plugin install lastlight@lastlight-skills.

Setup wizard

lastlight setup                       # first-run wizard — asks: client (login) or server (stack)
lastlight setup --client              # skip the prompt: configure this machine as a client
lastlight setup --server              # skip the prompt: run the full server config wizard

Global flags