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.

For Firecracker cells, attach uses Remote-SSH to the appliance host workspace (/cells/<cell-id>/workspace on the Tailscale-reachable host), not guest SSH inside the microVM. Container cells with a docker:// workspace endpoint use attached-container URLs by default; pass --host-fs to force host filesystem attach.

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.