CLI Lifecycle

The Go CLI talks to generated Connect clients. It can use paired HTTPS appliance hosts or plain local HTTP for development.

nix develop -c go run ./cmd/celld --http-dev --state /tmp/devcell.db

Create a cell:

nix develop -c go run ./cmd/devcell cell create \
  --name open-seat \
  --repo github.com/example/open-seat \
  --branch main

List cells:

nix develop -c go run ./cmd/devcell cell list

Inspect one cell:

nix develop -c go run ./cmd/devcell cell inspect cell_...

Start, stop, and destroy:

nix develop -c go run ./cmd/devcell cell start cell_...
nix develop -c go run ./cmd/devcell cell stop cell_...
nix develop -c go run ./cmd/devcell cell destroy cell_... --yes

Inspect an operation:

nix develop -c go run ./cmd/devcell operation get op_...
nix develop -c go run ./cmd/devcell operation watch op_...

Add --json to commands for machine-readable output.

Pair and open

devcell host pair --endpoint https://devcell-appliance:8080
devcell cell open cell_... --ide cursor --open

Pairing opens a browser approval page and pins the host TLS fingerprint. cell open resolves the live workspace and emits the IDE attach target for the appliance.

Snapshots, sleep, and fork

Sleep is volume checkpoint + stop (not RAM suspend). It creates a named snapshot, then stops the cell. Resume with cell start.

nix develop -c go run ./cmd/devcell cell sleep cell_... --snapshot-name sleep-checkpoint
nix develop -c go run ./cmd/devcell snapshot create cell_... --name before-change
nix develop -c go run ./cmd/devcell snapshot list cell_...
nix develop -c go run ./cmd/devcell cell fork cell_... --snapshot snap_... --name fork-name

Golden-fixture E2E script and manual steps: docs/cli-snap-fork-e2e.md (scripts/snap-fork-e2e.sh).

Workspace planning

Inspect a repository’s devcontainer inputs without contacting celld:

nix develop -c go run ./cmd/devcell workspace plan examples/workspaces/devcontainer-basic
nix develop -c go run ./cmd/devcell workspace plan examples/workspaces/devcontainer-basic --json

The planner normalizes devcontainer JSONC, Dockerfile, Compose, features, mounts, environment, and forwarded ports into a local workspace plan.

Published ports (container backend)

On the appliance container backend, forwarded ports are published to 0.0.0.0 on the host. devcell cell list-ports and devcell cell expose-port show endpoints using the appliance Tailscale IP when joined. HTTP and HTTPS ports also get a stable private route on the appliance when celld runs with --private-routes-listen (default :8443 on the NixOS appliance image):

http://<appliance-tailscale-ip>:8443/cells/<cell-id>/ports/<port>/

From a paired Mac:

devcell cell list-ports cell_...
devcell cell expose-port cell_... --port 3000 --protocol http
curl "http://$(tailscale ip -4 devcell-appliance):8443/cells/cell_.../ports/3000/"

Routes are removed when a port exposure is revoked, the cell is stopped, or the cell is destroyed.