CLI reference
All cryochamber binaries and their commands. For cryo.toml and cryohub.toml fields, see Configuration.
Every binary accepts --version (print the version and exit) and --help.
Operator CLI (cryo)
Run these from inside a chamber directory unless noted otherwise.
| Category | Command | What it does |
|---|---|---|
| Lifecycle | cryo init [--agent <cmd>] | Initialize the directory: write cryo.toml, plan.md, NOTES.md, and README.md. Existing files are kept. Without --agent, uses the host-level default_agent from cryohub.toml (built-in default: pi). |
cryo start [--agent <cmd>] | Start the daemon. Reads cryo.toml and writes overrides to timer.json. | |
cryo start --max-session-duration 3600 | Override the session timeout for this run. | |
cryo status | Show whether the daemon is running, the current session number, and the next wake time. | |
cryo restart | Restart the running daemon. When it is installed as an OS service, restart the existing service without rewriting or removing it. | |
cryo cancel | Stop the daemon and remove the runtime state. | |
| Logs | cryo watch [--all] [--viewpoint cryo|agent] | Follow a log in real time. --all shows the log from the beginning. --viewpoint cryo (default) follows the structured event log; --viewpoint agent follows raw agent output (cryo-agent.log). |
cryo log | Print the full session log. | |
| Messaging | cryo send "<message>" [--from <name>] [--subject <text>] | Send a message to the agent's inbox; the daemon's inbox watcher wakes the agent. --from sets the sender (default human), --subject sets the subject (default: derived from the body). |
cryo receive | Read messages the agent sent to the outbox. | |
| Housekeeping | cryo clean [--force] | Remove runtime files such as logs, state, and messages. |
cryo ps [--kill-all] | List, or kill, every running cryo daemon on this machine. Run from anywhere. |
Hub (cryohub)
| Command | What it does |
|---|---|
cryohub start [--host <ip>] [--port <n>] [--default-agent <cmd>] | Install a service that survives reboot. Enforces bearer auth by default, printing the owner token on first run (cryohub token owner reprints it). The supplied host, port, and default agent update the saved host config. |
cryohub start --foreground | Run the hub in the current terminal instead of installing a service. |
cryohub stop | Uninstall the global hub service. |
cryohub restart | Restart the installed global hub service without reinstalling it. |
cryohub status | Show the global hub URL, mode (public (bearer auth) or open (loopback)), chamber root, config path, log path, console source (embedded, or the console_dir override and whether a build is present), and service status. Also lists legacy cwd-scoped hub services from older versions. |
cryohub start --public | Enforce bearer-token auth on every /api route — the default. Creates the owner token if there is none and prints it. Saved to cryohub.toml, so a later plain cryohub start, a restart, or a reboot stays authenticated. |
cryohub start --no-public | Run without authentication (open mode, loopback only). Sharing and invites do not work in open mode. Required: disabling auth is never implicit, and a later plain cryohub start keeps the saved open mode. |
cryohub token owner | Print the owner token, creating it on first use. Idempotent — repeat runs print the same secret. |
cryohub token create --name <name> --chambers <id,...> | Mint a named invite scoped to those chamber ids. Prints the token and its #invite= link fragment; this is the only time the secret is shown. |
cryohub token list | List invites with scope, creation time, and revocation status. Never prints token strings. |
cryohub token revoke <name> | Revoke an invite by name. Takes effect immediately, including on already-open SSE streams. Fails if no active invite has that name. |
Agent IPC (cryo-agent)
These commands are used by the spawned AI agent to communicate with the daemon over a Unix socket. They are not the operator interface.
| Category | Command | What it does |
|---|---|---|
| Hibernating | cryo-agent hibernate --summary "..." | End the session; more work remains. Refused (non-zero exit) while unread inbox mail exists — the agent must receive, reply, and retry, so a session never ends with mail waiting for it. Also refused while no pending TODO declares the next wake. A successful call may block up to the reply window the agent requested with --linger <seconds> (omitted = 300, capped at 86400; 0 sleeps immediately). |
cryo-agent hibernate --complete | End the session; the plan is done. Additionally refused while a TODO is due. Never held open by the reply window. | |
cryo-agent hibernate --exit 1 | Report a failed session. The daemon marks consumed TODOs done and adds a fresh numbered retry TODO. Failure reports are never refused and never held open. | |
| TODOs | cryo-agent todo add "text" --at <TIME> | Schedule the next wake via a TODO. --at accepts a relative offset (+30 minutes), an ISO 8601 timestamp (2026-04-25T10:00; seconds and a space separator are tolerated), or a date only (2026-04-25, meaning midnight). |
cryo-agent todo list | List all TODO items. | |
cryo-agent todo done <id> | Mark a TODO item as done. | |
cryo-agent todo remove <id> | Remove a TODO item. | |
| Messaging | cryo-agent send "message" | Write a message to the outbox for the human. After claiming a thread, the daemon routes the message back to that thread automatically. |
cryo-agent send --stdin | Read the outbox message body from stdin exactly, including trailing newlines; use for multi-line or shell-sensitive text. | |
cryo-agent send --question "msg" | Mark the message as a question awaiting a human reply. | |
cryo-agent receive | Claim one pending conversation from the human: the first pending thread, or the unthreaded main-stream messages. A thread claim includes its root and reply history. Hub attachment links are returned as local messages/attachments/... paths. Reply before claiming another conversation. | |
cryo-agent dialog [--last N | --all | --since <iso>] | Render the conversation transcript (default: last 20 messages). --last N shows the last N, --all shows every archived message, --since <iso> shows messages at or after an ISO 8601 time; the three are mutually exclusive. Also claims and archives at most one pending conversation. A new thread claim includes its root and full history despite the requested limit; later reads stay in the active thread and honor that limit. Hub attachment links become local messages/attachments/... paths. | |
| Time | cryo-agent time | Print the current local time in ISO 8601 format. |
cryo-agent time "+30 minutes" | Compute a relative offset. Units: minutes, hours, days, weeks. | |
cryo-agent time "2026-04-25T10:00" | Validate and normalize an ISO 8601 timestamp. |
Zulip Sync (cryo-zulip)
| Command | What it does |
|---|---|
cryo-zulip init --config <zuliprc> --stream <name> [--topic <topic>] [--history] | Validate credentials, resolve the stream, and write zulip-sync.json. |
cryo-zulip sync [--interval N] | Start the background sync daemon. Default interval comes from cryo.toml or falls back to 5 seconds. |
cryo-zulip unsync | Stop the sync daemon. |
cryo-zulip pull | One-shot pull. |
cryo-zulip push | One-shot push. |
cryo-zulip status | Show sync configuration. |