> ## Documentation Index
> Fetch the complete documentation index at: https://tesser.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI reference

> Every verb, its contract, and its output discipline

The CLI is the product surface. Its contracts hold everywhere:

* Commands that **create or select** print the resulting ID as their *only*
  stdout. Progress and diagnostics go to stderr. Agents capture stdout and
  never parse prose.
* `exec` and `logs` pass the remote exit code through **verbatim**.
* Read commands take `--json`.
* Destructive commands don't confirm (`rm`, `stop`); creation is idempotent
  (retrying a failed `make` cannot double-launch).

## Boxes

### `tesser make [service] [--ensure-running <sha>]`

Creates a box, claiming a warm-pool blank when one is available (seconds)
and cold-launching otherwise. Prints the `box_…` ID.

* **No service argument** → a **workbench**: the current worktree synced to
  a box, nothing serving. The default target for `exec`.
* **With a service** (or a manifest path) → an **instance box** for that
  service. The service is a birth parameter; a repo with multiple manifests
  must name one — ambiguity is a loud error listing the options.
* **`--ensure-running <sha>`** → a **pinned instance**: idempotent — if that
  (service, sha) already runs, prints its existing box ID and exits. Content
  is materialized locally as a standalone shallow clone at the sha and
  pushed; `setup` then `dev` run from the manifest; readiness gates on the
  health check; a prior pinned instance of the service is replaced
  blue/green (alias flips atomically, old box drains, then is removed).

### `tesser ls [--json]` / `tesser status <box_id> [--json]`

Boxes with class, service, power state, and activity. The recovery path
when an agent loses an ID — cells are authoritative and EC2 tags stay
legible, so `ls` is always trustworthy.

### `tesser rm <box_id>`

The box ceases to exist: disk, instance, mesh registration, overrides
referencing it. Unrecoverable. Never asks for confirmation.

### `tesser sleep <box_id>`

Powers the box down; ID, private IP, and disk persist. Rarely needed by
hand — the reaper sleeps idle boxes (instance boxes at 2h, workbenches at
10m) and removes boxes asleep 16h. There is no `wake` command: **any
operation targeting a sleeping box wakes it** transparently, re-running the
`dev` recipe on instance boxes.

## Code and commands

### `tesser sync <box_id> [--restart] [--force]`

Mirrors the current worktree to the box. Unchanged trees short-circuit on a
fingerprint; a sync that would delete most of the remote tree aborts (wrong
worktree?) unless `--force`. `--restart` re-runs the `dev` recipe after an
effective sync and waits for health — for changes the server can't
hot-absorb; the agent decides when. `exec` and `dev` sync implicitly first.

### `tesser exec [box_id] [--in <service>] [--deps-of <service>] -- <cmd…>`

Runs a command in the synced workspace and streams stdio; the remote exit
code is the local exit code.

* With no box ID, targets the worktree's **workbench**, creating one on
  first use — tests and typechecks never contend with a dev server.
* `--in <service>` runs in that service's `root` directory.
* `--deps-of <service>` applies that service's `[deps]` bindings to the
  workbench for the duration — integration tests reach `localhost:5432`
  exactly as the service would.

### `tesser dev <service|box_id> [--force] -- [cmd…]`

Starts (or replaces) the dev instance for a service from the current
worktree: creates or reuses the (worktree, service) box, syncs, runs
`setup` if needed, ensures the manifest's deps (**ensure-on-use** — pinned
deps start or wake as required), runs the `dev` recipe, waits for health,
wires the cohort, registers the viewport target. Prints the box ID.
Re-running replaces the server — that is also the crash-recovery path. An
explicit trailing command overrides the manifest's `dev` recipe.

### `tesser logs <box_id> [-f]`

Tails the instance's log over SSH — last 200 lines, or follow. Logs live on
the box; nothing streams through the control plane.

### `tesser stop <box_id>`

Stops the running instance (process level). The box stays awake; the mesh
deregisters the instance. Distinct from `sleep` (power) and `rm`
(existence).

## Mesh and viewport

### `tesser use <box_id|name>`

Points the default viewport (`localhost:3000`) at a target. The panel
injected into proxied pages and the widget are the primary switching
surface; `use` is the scriptable form. Any box is also always directly
addressable at `<boxid>.localhost:<port>` — Host-routed, no selection
involved.

Per-name mesh overrides ("this box's `backend` goes to *my* backend") are
written through the panel or `use`-style commands and stored per box;
cohort auto-wiring covers the common case without any command at all.

### `tesser env set <service> KEY=VALUE…` / `tesser env ls <service>`

Sets control-plane-held env values for a service. `ensure-running` fails
loudly if a manifest's `env.required` names are unset. Values never live in
the repo.

## Fleet

### `tesser pool fill [N]` / `pool ls` / `pool drain`

Maintains machine-warm blanks for instant claims. Unclaimed pool boxes
self-destruct on a timer.

### `tesser daemon`

Runs `tesserd`: the viewport proxy and Host router, SSH tunnels, laptop dep
bindings, and the switcher widget/panel APIs.

### `tesser nuke [--force]`

Terminates every tesser-managed instance in the account after listing them
and confirming. The blast-radius backstop.