lea · Start

Commands

lea                          # the deck, for $LEA_PROJECTS_DIR (unset: the working directory, on the first run)
                             # (LEA_DECK=0: your own tool in the lea container, see Without the deck)
lea attach [--print] [AGENT] # the tool in the lea container, or an agent's terminal (--print: the command)
lea web [--open] [--port N]  # the deck in your browser, on 127.0.0.1 (see The deck in your browser)
lea requests                 # what waits for you; lea approve ID [always], lea deny ID [reason]
lea questions [drop ID]      # the control towers' questions to you: the open one, then the queue
lea hold [--off] [AGENT]     # hold the messages agents send the tower while you answer it; --off releases them
lea config deck on|off       # the deck, or your own tool (lea config tool CMD...), from the next lea
lea config claude [KEY ...]  # Claude's base settings for your agents (defaultMode, allow, deny, env...)
lea new [name] [-- args]     # one more agent (its CLI's arguments after --; -p provider, -m model)
lea shell [-- cmd...]        # a shell, or one command, in the same lea
lea stop [--all] [--forget] # stop this lea (--all: every lea); the next lea resumes its agents
                             # in their Claude conversations (--forget: drop them for good)
lea update [--deps ask|all|none]  # the latest release, its images, then newer dependencies
lea rollback                 # back to the previous version; the background update skips this one
lea doctor                   # check the setup
lea init                     # set up again (idempotent)
lea config export > team.json  # your team's shared settings, as one file
lea config import team.json  # take them on another workstation (see Configure)
LEA_PROJECTS_DIR=~/other lea # another projects directory, for this call only
lea allow [deliver|CAPABILITY...|off N|log]  # what agents may do without asking (see Allowances)
lea approve gN               # approve a lead's grant request (lea requests lists them; see Allowances)
lea github login|logout|status  # lea's GitHub token, in the proxy only (see Git and forges)

Update #

One command per install method; each pulls the new version's images, then names the Lock clients (update-deps):

• Homebrew: lea update runs brew update and brew upgrade davidgodefroid/tap/lea, then the new version pulls its images. It never installs a second lea beside Homebrew's, and fails with brew's status when brew fails. brew upgrade lea alone works too: the next lea pulls the images it lacks and restarts the daemon on the new binary. Old versions are brew cleanup's.
• install.sh: lea update, or the daily background update below.
• git checkout: lea update pulls and rebuilds (see Install from source).

A release install updates itself: at most once a day, lea looks for a new release in the background. A newer minor or patch release is installed beside the current one (its signature checked with cosign) and becomes active at the next lea; a newer major release is only announced in the deck, and so is a newer minor release while lea is 0.x (only its patch releases install themselves). Running containers keep their image until they stop. LEA_AUTOUPDATE=0 in ~/.config/lea/lea.conf turns it off; the log is ~/.local/share/lea/host/update.log. A Homebrew install has it off (its formula sets LEA_AUTOUPDATE=0); turned back on, it only announces a new release, which lea update installs with brew.

The Locks' clients in lea's image (locksql, lockmq, lockfile, locklog) come from one set of releases, config/locks.lock: for each Lock, the client's release, the protocol its handshake speaks, the release's image by digest and the identity that signed it. lea's CI bumps the set as a whole (tools/locks-bump checks every signature with cosign), and a lea release ships it as it is: lea update moves the clients together, never one by one, and installs, builds or starts no Lock: lox does (brew upgrade lox, lox add TYPE NAME --version vX.Y.Z, lox run). lea doctor compares each lock lox runs with lea's client of its type, from the image lockfamily.yaml pins or, for another image, from the lock console's own hello handshake (lea lock-hello, run in lea's image with only that lock's socket volume), and says what to run: lea update for a lock newer than lea's client, brew upgrade lox then lox add TYPE NAME --version for an older one; a pair whose protocols differ fails (every call of the agents would be refused). The handshake speaks the protocol of lea's client (lea lock-hello --protocol N): a console of another protocol refuses it ("protocol mismatch", naming its own), and lea doctor fails that lock with the fix. lea warns at the start about a lock that lockfamily.yaml pins to an image of another release. LEA_LOCKSQL_REF, LEA_LOCKMQ_REF, LEA_LOCKFILE_REF and LEA_LOCKLOG_REF remain for this release as a dev override of a client's version (lea doctor warns while one is set); LEA_LOCKSQL_IMAGE is obsolete.

After an update only the current and the previous versions stay in ~/.local/share/lea-install (never the one a running daemon still uses). lea rollback links the previous version again and sets LEA_AUTOUPDATE_SKIP=<this version> in ~/.config/lea/lea.conf, so the background update does not reinstall it (lea update still does); it fails when there is no previous version.

Each projects directory gets its own container, internal network, Claude history and login. The projects directory cannot be /, your home directory or one of its parents, nor overlap ~/.claude or lea's own directories.