CLI reference

The zeno CLI is the operator's entry point for daily ops. It talks directly to the Docker socket via dockerode and stores profile metadata in ~/.zeno/state.db.

The flag tables below are generated at docs build time from the citty args schemas in apps/cli/src/commands/<cmd>.ts — when a flag is added or renamed, the next zeno-docs deploy carries it without anyone touching this page.

Profile management

zeno profile create

Creates a new profile, allocates a host port, generates a master key, and scaffolds ~/.zeno/profiles/<name>/USER.md and .env from the templates under templates/profile/.

zeno profile create personal --owner "Alice"

Flag	Type	Default	Description
<profile>	positional	—	profile identifier (lowercase kebab-case, e.g. "personal
--owner	string	—	how Zeno calls you (goes to USER.md). Prompted if omitted.
--port	string	—
--yes	boolean	—	skip prompts, use placeholder for missing fields

zeno profile list

Inventory of every profile in state.db, with live container status and dashboard port.

zeno profile list

This subcommand takes no flags.

zeno profile show

Full detail block for a single profile.

zeno profile show personal

Flag	Type	Default	Description
<profile>	positional	—	profile identifier

zeno profile edit

Move a profile's host port. Useful when a port is already taken.

zeno profile edit personal --port 6105

Flag	Type	Default	Description
<profile>	positional	—	profile identifier
--port	string	—

zeno profile use

Set the sticky profile that subcommands act on when no profile argument is given.

zeno profile use personal

Flag	Type	Default	Description
<profile>	positional	—	profile identifier

zeno profile delete

Remove a profile: container, both volumes, the ~/.zeno/profiles/<name>/ directory, and the state.db row. Prompts before destroying anything.

zeno profile delete personal

Flag	Type	Default	Description
<profile>	positional	—	profile identifier

zeno profile

The umbrella subcommand. Running it with no further arg prints the available verbs.

This subcommand takes no flags.

Lifecycle

zeno start

Start a profile container. Auto-builds the zeno-agent:dev image if it's missing.

zeno start personal
zeno start --all
zeno start personal --build

Flag	Type	Default	Description
<profile>	positional	—	profile identifier (omit for sticky)
--all	boolean	—
--build	boolean	—	force rebuild of zeno-agent:dev image before start

zeno stop

Stop a profile container without removing it.

zeno stop personal
zeno stop --all

Flag	Type	Default	Description
<profile>	positional	—	profile identifier (omit for sticky)
--all	boolean	—

zeno restart

Stop + start. Cheapest way to pick up an env change.

zeno restart personal

Flag	Type	Default	Description
<profile>	positional	—	profile identifier (omit for sticky)
--all	boolean	—
--build	boolean	—

Inspect

zeno logs

Tail container logs. SIGINT (Ctrl-C) to abort.

zeno logs personal --tail 100

Flag	Type	Default	Description
<profile>	positional	—	profile identifier (omit for sticky)
--tail	string	—

zeno open

Open the profile's dashboard in the system browser.

zeno open personal

Flag	Type	Default	Description
<profile>	positional	—	profile identifier (omit for sticky)

zeno doctor

Preflight diagnostics: docker reachable, drift between state.db and the running Docker world, etc. Reports findings; does not heal.

zeno doctor

This subcommand takes no flags.

Updates

zeno upgrade

Switch the local clone to a different release. With no flags, drops into a TTY arrow-key picker over the available stable releases. With --list, prints a table and exits. With --to, pins to a specific tag. With --prerelease or --edge, opens the picker over the alternate channels.

zeno upgrade
zeno upgrade --list
zeno upgrade --to v2026.5.7-7

Flag	Type	Default	Description
--to	string	—
--prerelease	boolean	—	include pre-releases when picking latest
--edge	boolean	—
--latest	boolean	—	jump straight to latest stable (skips the picker)
--list	boolean	—
--force	boolean	—

Misc

zeno repo

Print the canonical repo path. Useful in shell scripts that need to cd into the source tree.

cd "$(zeno repo)"

This subcommand takes no flags.