Command reference

The small surface area.

Run celln --help for the authoritative reference installed with your version. These are the commands most people need.

Daily commands

Command	Purpose
`celln doctor`	Report whether this machine can create a hardware-isolated cell.
`celln setup`	Discover provider CLIs, save a default, and materialise the default tool images. `--tools` selects, `--no-tools` skips.
`celln providers`	List the inference providers this host can use; add `--set-default` to change one.
`celln image add <image:tag>`	Resolve a tag to its digest, materialise it, and add it to this host's catalogue. `--tool alias=path` names what to expose; `celln image remove` drops it.
`celln image list`	What is materialised on this host, by name, with size and a short digest.
`celln image catalogue`	The digest-pinned images celln ships, and which are materialised here.
`celln image pull <name>`	Materialise a catalogue image (or any `name@sha256:…`) into a sealed filesystem. Tags are refused.
`celln image spec <name>`	Scaffold a runnable spec for a catalogue image.
`celln ps -a`	Show recent cells and their outcome.

Let a model write the program

celln agent --tool python "print the first 12 fibonacci numbers"
celln agent --show-source "Write a fizzbuzz program"
celln agent --provider anthropic "Build a small CLI"
celln agent --allow-host example.com "Fetch and summarize https://example.com"

Run declared tools

celln image pull python              # once, ahead of time
celln image spec python > agent.toml
celln spec check agent.toml
celln agent agent.toml               # --prompt overrides the spec prompt
celln run reviewed.toml              # a pinned [run] invocation

A tool comes from one of three places: path for a single binary on this host, image + exec for a dependency closure, or builtin = "fetch" for the brokered HTTPS capability. A cell can declare several [[run]] invocations and mount several images at once. An [agent] block lets a model write the program instead, with the spec keeping the policy. The tutorial walks through all three.

The spec names the tool bytes and execution plan. Validation catches an undeclared executable or an interpreter that would consume agent-authored input before a cell is created.

Inspect and reproduce

celln verify          # guest attempts the hardware boundary checks
make bench-kvm        # measurements on a capable KVM host
celln ps -a --json