Operator CLI (`colibri`)

Operator CLI (colibri)

← index

The colibri binary is the operator's command-line interface to the daemon.

It wraps a typed Unix-socket client (DaemonClient) and turns typed commands

into newline-delimited JSON messages on the control-plane socket. It is not

where policy lives — policy lives in the daemon behind the socket.

Job of the CLI

The CLI has two responsibilities:

1. Parse shell input into strongly-typed commands.

2. Send those commands to the daemon and print the JSON response.

It does not contain business logic about session compaction, task scheduling,

or jail confinement. That keeps the CLI small and lets any other client (TUI,

MCP bridge, web dashboard, tests) perform the same operations with the same

protocol.

→ crates/colibri-client/src/bin/colibri.rs (argument parsing and run dispatch)

→ crates/colibri-client/src/lib.rs (DaemonClient request/response wrapper)

Decisions

One binary, one socket, one protocol

Every command — status, snapshot, spawn-agent, create-task,

and reads one ColibriResponse line back.

Because the protocol is newline-delimited JSON, operators can still debug with

the CLI is a polished client.

→ crates/colibri-daemon/src/lib.rs (ColibriCommand, ColibriResponse)

→ crates/colibri-daemon/src/socket.rs (dispatch table)

Socket resolution order matches other clients

The CLI resolves the daemon socket the same way the TUI and MCP bridge do:

1. --socket PATH

2. COLIBRI_DAEMON_SOCKET

3. DaemonConfig::from_env().socket_path

Sharing the resolution order means documentation, environment setup scripts,

and operator muscle memory apply to every client.

→ crates/colibri-client/src/bin/colibri.rs (default_socket_path)

No write-gating inside the CLI itself

Commands that mutate state (create-task, kill-agent, set-cost-mode,

itself: the daemon is configured to listen on a unix socket with operator-only

permissions, and the daemon validates each command. This avoids two parallel

permission layers that could drift out of sync.

This is an intentional contrast with colibri-mcp, which exposes the daemon to

editor assistants and therefore uses COLIBRI_MCP_WRITE=1 as an explicit trust

switch. An operator at the shell already has that trust by virtue of the socket.

→ external-mcp

Commands return JSON, not human prose

All successful CLI commands print pretty-printed JSON. This keeps the output

scriptable (colibri snapshot | jq '.panes[] | select(.state == "working")')

and consistent with the socket protocol. If a command fails, the CLI prints the

daemon's error message to stderr and exits non-zero.

→ crates/colibri-client/src/lib.rs (request, error handling)

spawn-agent accepts jail confinement directly

The --jail-name and --jail-root flags on spawn-local and spawn-agent

build a JailConfig that is sent to the daemon. The same type is re-exported

from colibri-daemon::spawner so the CLI crate does not have to depend on the

daemon crate just to build a config.

Pairing --jail-name with --jail-root is the only path that triggers vault

provisioning after a spawn, because the daemon needs both the jail identity

and the host-visible jail root.

→ crates/colibri-client/src/lib.rs (JailConfig re-export)

→ crates/colibri-daemon/src/spawner.rs

Local sample agent lives next door

The same crate also ships colibri-test-agent, a tiny sample binary used by

tests and the TUI's spawn shortcut. Keeping it in colibri-client keeps the

sample close to its primary caller without adding a new crate.

→ crates/colibri-client/src/bin/colibri_test_agent.rs

Notable commands

See also

• tui — the live terminal dashboard that uses the same DaemonClient
• glasspane — the pane state machine behind snapshot
• task-board — commands that manipulate the task board
• store-schema — SQLite entities queried by the CLI
• vault-provision — why register-tenant carries a jail root path
• external-mcp — another daemon client with write-gating