CLI Reference

The compozy CLI is the control surface for the local Compozy daemon. Use it to bootstrap the home directory, start the daemon, create durable sessions, inspect workspaces, manage skills and extensions, and query runtime state over the daemon socket.

Rendering diagram…

The CLI groups commands by the runtime surface they operate: daemon process, durable work, project context, capabilities, observability, and local setup.

Command Groups

Agents

Inspect resolved agent definitions

Use this group to list available agents and inspect one resolved definition by name.

Discovery

Sessions

Create, resume, prompt, wait on, and inspect sessions

Use this group for durable agent work: `new`, `list`, `resume`, `events`, `history`, `status`, `prompt`, `wait`, and `stop`.

Core workflow

Tasks

Create tasks and operate task runs

Use this group for queued work, dependencies, child tasks, approvals, and run lifecycle.

Durable work

Workspaces

Use this group to add, list, inspect, edit, or remove workspace registrations.

Project scope

Daemon

Start and stop the background runtime

Use this group for daemon lifecycle. Use `compozy status` and `compozy doctor` for runtime inspection.

Runtime process

Status

Read consolidated runtime state

Use this command for daemon, session, provider, MCP, task, bridge, config, and log-tail status over the shared public contract.

Runtime process

Doctor

Run runtime diagnostics

Use this command for DiagnosticItem-backed health checks that match the HTTP and UDS doctor payload.

Diagnostics

MCP

Install, authorize, and inspect MCP integrations

Use this group for curated install, remote MCP OAuth completion, redacted auth status, refresh diagnostics, and logout.

Runtime integrations

Automation

Manage jobs, triggers, and runs

Use this group for scheduled work, event-triggered work, and run history.

Queued work

Hooks

Inspect hook catalog, events, and run history

Use this group when you need to understand what lifecycle hooks exist and how they executed.

Policy

Bridges

Manage platform bridge instances

Use this group for bridge instance creation, routing, lifecycle, and delivery tests.

External channels

Vault

Manage encrypted daemon Vault metadata

Use this group to list redacted metadata, write values from stdin, inspect one ref, and delete refs.

Secrets

Marketplace

Discover installable capabilities

Use this group to search MCP servers, extensions, skills, and bundles, inspect stable catalog entries, and refresh feed-backed kinds.

Capability discovery

Skills

Create, inspect, install, update, and remove skills

Use this group for local AgentSkills and marketplace-installed skill directories.

Agent capability

Memory

Show, write, search, and operate Memory v2

Use this group for scoped durable memory, controller decisions, recall, and dream triggers.

Durable context

Extensions

Install, enable, disable, update, and inspect extensions

Use this group for the extension marketplace and installed extension state.

Runtime plugins

Tools

Inspect and invoke registry tools

Use this group to list, search, info, and invoke tools through the operator projection. Agents call the same tools through the registry directly.

Tool registry

Toolsets

Inspect registry toolsets

Use this group to list and expand named toolsets such as compozy__bootstrap, compozy__catalog, and compozy__autonomy.

Tool registry

Network

Inspect peers, channels, inboxes, and send envelopes

Use this group when a session participates in Compozy Network coordination.

Coordination

Observe

Query global observability streams

Use this group for global event history and observability views. Runtime health moved to `compozy status` and `compozy doctor`.

Observability

Completion

Generate shell completion scripts

Use this group to install Bash, Zsh, Fish, or PowerShell completion for `compozy`.

Shell setup

Bootstrap

Initialize ~/.compozy and the default general agent

Use this command when you are setting up Compozy on one machine for the first time.

First run

Identity

Inspect the agent identity exported into the current environment

Use this command inside managed sessions or automation when you need the current Compozy identity envelope.

Environment

Version

Inspect the installed Compozy build

Use this command to confirm the binary version before debugging or filing issues.

Build info

Global Options

The current CLI has one persistent flag inherited by every user-facing command.

Flag	Default	Values	Behavior
`-o, --output string`	`human`	`human`, `json`, `toon`	Selects output rendering. Use `json` for scripts and `toon` for compact agent-readable output.
`-h, --help`	n/a	n/a	Added by Cobra for every command. Prints command usage and exits.

There is no global --config, --log-level, or --socket flag today. These settings come from the Compozy home directory and config.toml.

Input	Default	Effect
`COMPOZY_HOME`	`~/.compozy`	Overrides the global Compozy home directory. This changes the default config path, socket path, log path, session store, skill store, and memory store together.
`~/.compozy/config.toml`	created by `compozy install`	Global configuration loaded by the daemon and most CLI commands before they contact the socket.
`[daemon].socket`	`$COMPOZY_HOME/daemon.sock`	Overrides the Unix domain socket path used by daemon clients. Empty values fall back to the Compozy home socket.
`[log].level`	`info`	Controls daemon structured logging. Accepted values are `debug`, `info`, `warn`, and `error`.
`[http].host`, `[http].port`	`localhost`, `2123`	Controls the daemon HTTP/SSE bind address exposed behind the runtime.
`COMPOZY_SESSION_ID`	injected into managed agent sessions	Identifies the current Compozy session for agent-side CLI calls and `compozy whoami`.
`COMPOZY_SESSION_CHANNEL`, `COMPOZY_PEER_ID`	injected only for executions resolved as Live	Identify the immutable participation channel and daemon-owned peer identity for agent-side `compozy network` calls.
`COMPOZY_AGENT`, `COMPOZY_AGENT_NAME`	caller-provided when present	Read by `compozy whoami`; current session launch code does not synthesize these values.

Example: run a separate Compozy home for a demo without touching your normal daemon.

COMPOZY_HOME="$PWD/.compozy-demo" compozy install
COMPOZY_HOME="$PWD/.compozy-demo" compozy daemon start
COMPOZY_HOME="$PWD/.compozy-demo" compozy status --output json

Example: set the daemon socket and log level in ~/.compozy/config.toml.

[daemon]
socket = "~/.compozy/custom-daemon.sock"

[log]
level = "debug"

Common Workflows

Start Daemon and Create a Session

Use this sequence after compozy install has created a global config and a default general agent.

compozy daemon start
compozy workspace add "$PWD" --name current
compozy session new --workspace current --agent general --name first-run

Then inspect the session and follow its event stream.

compozy session list
compozy session events sess_1234 --follow

The daemon start command waits until the socket responds. If a daemon is already running, it returns an error instead of starting a second process.

Attach to a Session

Live sessions expose an explicit attach path. List eligible sessions with --resumable, attach by ID, and use recap when you need a deterministic read-only reconstruction.

compozy session list --resumable
compozy session resume sess_1234
compozy session recap sess_1234
compozy session status sess_1234

compozy session resume attaches to an eligible live session. It does not start a new provider subprocess or rewrite transcript history. Terminal sessions stay available through compozy session recap, compozy session events, and compozy session history.

Manage Workspaces

compozy workspace add "$PWD" --name checkout-api --default-agent reviewer
compozy workspace list
compozy workspace info checkout-api

Edit the registration when the project moves or its default agent changes.

compozy workspace edit checkout-api --name checkout
compozy workspace edit checkout --default-agent ""
compozy workspace remove checkout

compozy session new --workspace <name-or-id> uses a registered workspace. compozy session new --cwd <absolute-path> asks the daemon to use an absolute path directly and auto-register it when needed.

Shell Completion

Cobra generates completion scripts from the same command tree used for the reference pages.

Shell	Setup
Bash	`compozy completion bash > "$(brew --prefix)/etc/bash_completion.d/compozy"`
Zsh	`compozy completion zsh > "$(brew --prefix)/share/zsh/site-functions/_compozy"`
Fish	`compozy completion fish > ~/.config/fish/completions/compozy.fish`
PowerShell	`compozy completion powershell > compozy.ps1`

See the generated completion pages for shell-specific notes:

Full Command Tree

compozy
|-- agent
|   |-- info <name>
|   `-- list
|-- automation
|   |-- jobs
|   |   |-- create
|   |   |-- delete <id>
|   |   |-- get <id>
|   |   |-- history <id>
|   |   |-- trigger <id>
|   |   `-- update <id>
|   |-- runs
|   |   `-- get <id>
|   `-- triggers
|       |-- create
|       |-- delete <id>
|       |-- get <id>
|       |-- history <id>
|       `-- update <id>
|-- bridge
|   |-- create
|   |-- disable <id>
|   |-- enable <id>
|   |-- get <id>
|   |-- list
|   |-- restart <id>
|   |-- routes <id>
|   |-- test-delivery <id>
|   `-- update <id>
|-- completion
|   |-- bash
|   |-- fish
|   |-- powershell
|   `-- zsh
|-- daemon
|   |-- start
|   |-- status
|   `-- stop
|-- extension
|   |-- disable <name>
|   |-- enable <name>
|   |-- install <path-or-slug>
|   |-- list
|   |-- remove <name>
|   |-- search <query>
|   |-- status <name>
|   `-- update [name]
|-- hooks
|   |-- events
|   |-- info <name>
|   |-- list
|   `-- runs
|-- install
|-- memory
|   |-- consolidate
|   |-- delete <filename>
|   |-- list
|   |-- read <filename>
|   `-- write <filename>
|-- network
|   |-- channels
|   |-- inbox
|   |-- peers [channel]
|   |-- send
|   `-- status
|-- observe
|   |-- events
|   `-- health
|-- session
|   |-- events <id>
|   |-- history <id>
|   |-- list
|   |-- new
|   |-- prompt <id> <message>
|   |-- resume <id>
|   |-- status <id>
|   |-- stop <id>
|   `-- wait <id>
|-- skill
|   |-- create [name]
|   |-- info <name>
|   |-- install <slug>
|   |-- list
|   |-- remove <name>
|   |-- search <query>
|   |-- update [name]
|   `-- view <name>
|-- task
|   |-- approve <id>
|   |-- cancel <id>
|   |-- child
|   |   `-- create <parent-id>
|   |-- complete <run-id>
|   |-- create
|   |-- dependency
|   |   |-- add <task-id> --depends-on <depends-on-id>
|   |   `-- remove <task-id> <depends-on-id>
|   |-- fail <run-id>
|   |-- get <id>
|   |-- heartbeat <run-id>
|   |-- list
|   |-- next
|   |-- publish <id>
|   |-- release <run-id>
|   |-- run
|   |   |-- attach-session <run-id>
|   |   |-- cancel <run-id>
|   |   |-- claim <run-id>
|   |   |-- complete <run-id>
|   |   |-- enqueue <task-id>
|   |   |-- fail <run-id>
|   |   |-- list <task-id>
|   |   `-- start <run-id>
|   |-- start <id>
|   `-- update <id>
|-- tool
|   |-- info <id>
|   |-- invoke <id>
|   |-- list
|   `-- search
|-- toolsets
|   |-- info <id>
|   `-- list
|-- version
|-- whoami
`-- workspace
    |-- add <path>
    |-- edit <name-or-id>
    |-- info <name-or-id>
    |-- list
    `-- remove <name-or-id>

The hidden compozy doc command is intentionally excluded from the user-facing tree. It exists only so the repository can regenerate these reference pages.

On this page