CLI Reference

cheasee-pi is the Docker-based launcher for the pi coding agent. It sets up a workspace, launches pi inside a container with provider keys injected, and manages the container lifecycle. This page is the command reference — every command’s does, checks, and inputs at a glance. For step-by-step setup and daily walkthroughs, see Installation and Daily Usage.

At a glance

Command	Does	Key inputs
cheasee-pi (no args)	Launch pi in the container — alias of start	workspace, API keys
cheasee-pi start (alias up)	Launch pi inside the container with provider keys injected	workspace, --build to rebuild first
cheasee-pi init	Set up workspace: bare clone + main worktree + cheasee-settings.json	empty folder, repo URL
cheasee-pi auth add \| remove \| list \| envvars	Manage provider API keys	provider, key
cheasee-pi build (full: rebuild)	Rebuild the Docker image	workspace settings
cheasee-pi down (alias stop)	Stop/remove THIS workspace’s container only	—
cheasee-pi clean	Remove ALL cheasee-pi containers (every repo) — kills active sessions	confirmation
cheasee-pi prune-images	Delete ALL tagged cheasee-pi images (every repo) — recreated on next build	confirmation, --dry-run / --yes
cheasee-pi uninstall	Delete cheasee-pi itself: cache, auth config, binaries	confirmation
cheasee-pi about (alias intro)	Print a ~10-line glossary of core concepts + workflow links	—

cheasee-pi --version prints the CLI version. cheasee-pi --help lists every subcommand.

Lifecycle

Step	Command	What happens
1	cheasee-pi init	empty-folder workspace setup (clone, scaffold, auth)
2	cheasee-pi auth add <provider>	store API key, set default provider
3	cheasee-pi start	build image on first run, launch pi
4	(work)	interactive pi session inside the container
5	cheasee-pi down	stop and remove this workspace’s container
6	cheasee-pi clean	sweep every container + orphan sessions, prune
7	cheasee-pi prune-images	remove every tagged cheasee-pi-* image on the host + orphaned build cache

An empty folder can skip step 1: cheasee-pi start auto-runs init and stops (init never launches pi); run cheasee-pi start again to launch.

cheasee-pi (no args) / start

Launch an interactive pi session inside the container. The root command run without a subcommand executes the same handler as start.

Does	Mounts the workspace at /workspaces/main and its sibling bare clone at /workspaces/.bare, starts the container (docker compose up if not running), injects provider keys from ~/.config/cheasee-pi/auth.json as environment variables, launches pi, and prints the CodeFlow URL (http://localhost:<port>/?repo=local/workspace&run=1) once the container is healthy. The CodeFlow sidecar is published on loopback only by default (CODEFLOW_HOST_IP, default 127.0.0.1 — set 0.0.0.0 to opt in to remote access). It also starts the local ui sidecar and prints the control-center URL (ℹ UI: http://127.0.0.1:<port>), bound to loopback by the compose mapping (see UI below).
Checks	Workspace gate: empty folder → runs init and stops (re-run start to launch pi); cheasee-settings.json present → run; non-empty folder without it → refused with an empty-folder hint. Docker gate (binary present + docker info responds + Engine ≥ 24.0.0, 5 s timeout) unless --no-docker-check.
Inputs	Flags: --workdir, --name, --build, --no-docker-check, --api-key (session-only, not saved), --dry-run (print injected env vars, then exit). Reads auth.json + cheasee-settings.json; writes the version-keyed compose/Dockerfile cache.

UI (web control center)

cheasee-pi start also launches the local ui sidecar — the cheasee-pi web control center — and prints its URL once the container is healthy:

ℹ UI: http://127.0.0.1:9713

The URL is printed with the literal 127.0.0.1, never localhost: the compose mapping pins the host side to IPv4 loopback (127.0.0.1:<port>), and on hosts where localhost resolves to ::1 first a localhost URL would not reach the published port.

Resolution order for the host port: docker.uiPort in cheasee-settings.json → env PI_UI_PORT → derived 9500 + fnv32(repo-slug) % 1024 (range 9500–10523, probed next-free) so parallel workspaces never collide. The port the running sidecar actually published (docker port) is authoritative over that chain.

The resolved host port is forwarded into the pi session as PI_UI_PORT so the in-session footer link agrees with the printed ℹ UI: hint. When no free host port can be resolved (range exhausted) the CLI omits PI_UI_PORT, prints ⚠ UI port: <reason>, and sets CHEASEE_UI_PORT_UNRESOLVED=1; start still succeeds and the footer suppresses the UI link.

The host side is bound to loopback by configuration — there is no all-interfaces opt-in (unlike CodeFlow’s CODEFLOW_HOST_IP). This is not a hard isolation boundary: Docker Engine before 28.0.0 may expose a loopback-published port to hosts on the same L2 segment, and the supported floor is Engine 24.0.0. The container side stays 0.0.0.0:3000 (docker-proxy/DNAT delivery); the published host port is loopback-bound. See Daily Usage for the start/reconnect workflow and Security for the threat model.

cheasee-pi init

Set up a cheasee-pi workspace from scratch: bare clone to <workdir>/.bare, main worktree in the workspace subfolder (<workdir>/main by default), and the dedicated cheasee-settings.json scaffolded inside that worktree leaf (gitignored, machine-local). GitHub OAuth (device flow) is the primary authentication; --no-github falls back to the legacy API-key-only path (no clone, no repo URL).

Does	Bare-clones the project repo, adds the main worktree in the workspace subfolder (<workdir>/main unless a different workspace folder name is stated), scaffolds cheasee-settings.json in the worktree leaf (never overwrites an existing one), authenticates GitHub, records custom skill repos, saves auth config, and sets up the provider API key. Prints cheasee-pi start as the next step — init never launches pi (the second start invocation does).
Checks	Docker gate unless --no-docker-check. Empty-folder probe: non-empty folders are refused (.DS_Store tolerated). cheasee-settings.json presence marks the workspace initialized — init refuses it unless --reauth (which re-runs only the GitHub + API-key authentications). Single invocation capped at a 5-minute timeout (device-flow OAuth polling dominates). --no-input requires --repo-url.
Inputs	The GitHub repo pi should work on (--repo-url or interactive prompt; must already exist on GitHub), workspace folder name (interactive prompt, default main; names the subfolder only, not a git branch), GitHub OAuth device flow, API key (--api-key or prompt), provider name. Files written: cheasee-settings.json in the worktree leaf, ~/.config/cheasee-pi/auth.json, .pi/ agent settings, sibling .bare clone + worktree leaf.

init flags

Flag	Meaning
--workdir <dir>	Working directory (default: current directory)
--no-github	Legacy API-key-only path — skip the clone and GitHub OAuth entirely
--client-id <id>	GitHub OAuth app client ID (default: cheasee-pi’s app)
--provider <name>	Provider name for the API key (default: opencode-go)
--no-input	Skip all interactive prompts (--repo-url then required)
--api-key <key>	API key, skips the interactive prompt
--no-docker-check	Skip the Docker Engine check
--repo-url <url>	GitHub repo pi should work on (owner/repo or GitHub URL; required with --no-input)
--reauth	Redo GitHub + pi API-key authentications on an initialized workspace
--skill-repo <spec>	Custom skills installed into the container (repeatable)

cheasee-pi auth

Manage provider API keys. Keys live in ~/.config/cheasee-pi/auth.json (0600, atomic writes) and the last-added provider becomes the default in the workspace settings.

Subcommand	Does	Inputs / checks
auth add [provider]	Add or update a provider API key; sets it as the default provider (and model) in the workspace settings	provider name or interactive picker; --workdir, --no-input (skip model selection). Saves to auth.json + cheasee-settings.json + .pi/agent/settings.json
auth remove <provider>	Delete the key from auth.json	exact provider name; --workdir. Leaves defaultProvider/defaultModel in cheasee-settings.json untouched — switch the default with cheasee-pi auth add <other>
auth list	List configured providers (masked keys) + the workspace default	--workdir
auth envvars	Print the canonical provider→env var mapping (shell format by default)	--format shell\|json; emits no key values

cheasee-pi build / rebuild

Rebuild the Docker image without starting the container. build reuses the Docker layer cache; rebuild is a full no-cache rebuild plus prune.

Does	Rebuilds the image from the compose/Dockerfile in the version-keyed cache dir; passes CHEASEEPI_MEMORY from cheasee-settings.json as a build arg.
Checks	Runs from a git repo (settings + git identity come from it). Docker gate unless --no-docker-check. Compose validates every volume spec, so the workspace path must resolve.
Inputs	Flags: --workdir, --no-docker-check. Reads cheasee-settings.json (docker.memory).
Note	A cached build does not apply the new image to a running container — apply with cheasee-pi start --build or cheasee-pi down + cheasee-pi start.

cheasee-pi down

Stop/remove the current workspace’s container only — via docker compose down (alias stop).

Does	Removes the compose project derived from this workspace’s repo — sibling workspaces’ containers keep running.
Checks	No-ops when no container matches the workspace’s project. Legacy pre-derivation containers (project cheasee-pi) are deliberately not targeted — cheasee-pi clean removes those.
Inputs	None (no flags).

cheasee-pi clean

Remove ALL cheasee-pi containers (every repo) — kills active sessions and orphaned pi processes inside them.

Does	Enumerates ALL managed containers on the host (every repo, running or stopped), force-removes each, kills orphaned pi processes inside them, and prunes dangling images + build cache.
Checks	Lists the matches and asks for confirmation before killing anything (--yes skips, --dry-run previews). Default scope is every cheasee-pi container on the host — --name scopes to a single container.
Inputs	Flags: --name <container> (scope), --older-than <minutes> (orphan age reap; 0 disables), --dry-run, --yes.

cheasee-pi prune-images

Delete ALL tagged cheasee-pi images (every repo) — recreated on next build — the explicit “free the disk” step when repeated builds fill the Docker data root. clean removes containers; prune-images removes the regenerable per-repo images (cheasee-pi-<slug>-cheasee-pi, cheasee-pi-<slug>-codeflow) that clean never touches.

Does	Enumerates all tagged cheasee-pi-* images on the host (every repository, no keep-latest), force-removes each by full Repository:Tag, then prunes dangling images + build cache.
Checks	Refuses while any cheasee-pi container exists (running or stopped) — run cheasee-pi clean first; a running container is a hard Docker conflict -f cannot force, and force-removing a stopped container’s image silently orphans it. --dry-run lists the matched images with approximate (upper-bound) sizes.
Inputs	Flags: --dry-run, --yes (skip confirmation).
Note	Images are regenerable via cheasee-pi build / cheasee-pi rebuild. docker buildx prune -a -f discards cache host-wide — other projects sharing the default builder lose their cache too. Foreign tagged images are never matched.

cheasee-pi uninstall

Delete cheasee-pi itself: cache, auth config, binaries.

Does	Removes the version-keyed cache dir (compose/Dockerfile), ~/.config/cheasee-pi/auth.json, and every cheasee-pi binary (the running executable plus the canonical install locations ~/.local/bin and /usr/local/bin, deduped). Workspace files (.pi/, .git/, source checkouts) are never touched.
Checks	Shows a summary and asks for confirmation (--force skips). Skips build-cache/tmp binaries; warns when a binary’s directory is not writable.
Inputs	Flags: --force.

cheasee-pi about

Print a non-interactive glossary of cheasee-pi’s core concepts — workspace, bare repo, worktree, container/image, provider, skill repo, CodeFlow, and CHEASEE_REF — plus the one-sentence workflow, linking the long-form docs (docs/daily-usage.md) and the published rendering (https://schneiderdaniel.github.io/cheasee-pi/daily-usage).

Does	Prints the ~10-line glossary + workflow summary to stdout and links docs/daily-usage.md and pi.dev.
Checks	None — pure print.
Inputs	None (no flags). Alias: intro.

Environment variables

Provider keys are read from ~/.config/cheasee-pi/auth.json, not the environment — the mapping below is what the CLI injects into the container. cheasee-pi auth envvars is the canonical live source.

Provider	Env var
opencode-go (alias: opencode)	OPENCODE_API_KEY
openai	OPENAI_API_KEY
anthropic (alias: claude)	ANTHROPIC_API_KEY
deepseek	DEEPSEEK_API_KEY
gemini (alias: google)	GEMINI_API_KEY
groq	GROQ_API_KEY
mistral	MISTRAL_API_KEY
openrouter	OPENROUTER_API_KEY
xai	XAI_API_KEY
fireworks	FIREWORKS_API_KEY
together	TOGETHER_API_KEY
cerebras	CEREBRAS_API_KEY

Passthrough from the host environment (when set):

• GH_TOKEN, CLOUDFLARE_ACCOUNT_ID

Other variables the CLI reads:

Variable	Meaning
CODEFLOW_PORT	Host port for the CodeFlow sidecar. Resolution order: docker.codeflowPort in cheasee-settings.json → env CODEFLOW_PORT → derived 8470 + fnv32(repo-slug) % 1024, probed next-free
CODEFLOW_HOST_IP	Host-side bind IP for the CodeFlow sidecar’s published port. Default 127.0.0.1 — loopback only, matching the printed localhost URL (the sidecar serves the workspace source read-only). 0.0.0.0 is the explicit remote-access opt-in
PI_UI_PORT	Host port for the ui control-center sidecar. Resolution order: docker.uiPort in cheasee-settings.json → env PI_UI_PORT → derived 9500 + fnv32(repo-slug) % 1024, probed next-free. The host bind is bound to 127.0.0.1 by configuration (no opt-in). See UI
CHEASEEPI_MEMORY	Build arg passed by build/rebuild from docker.memory in cheasee-settings.json
XDG_CACHE_HOME (Unix) / LocalAppData (Windows)	Base for the CLI cache dir via os.UserCacheDir

Files and artifacts

Path	Role
~/.config/cheasee-pi/auth.json	Provider API keys + GitHub token/user (0600, atomic writes)
<workspace>/cheasee-settings.json	Initialized marker; defaultProvider/defaultModel, docker settings, skill repos (tab-indented, never overwritten by init)
<UserCacheDir>/cheasee-pi/<version>	CLI-managed cache: docker-compose.yml, Dockerfile (extracted on demand)
<workspace>/.pi/	pi agent config (settings, agent settings)
<workdir>/.bare	Sibling bare clone, mounted at /workspaces/.bare in the container
container cheasee-pi-<repo-slug>	Per-repo Docker container (workspace mounts at /workspaces/main)

Where to go deeper

• Installation — prerequisites, install, first setup, uninstall
• Daily Usage — start/stop flows, CodeFlow, parallel workspaces, troubleshooting