CLI Reference
First-class reference for the coven command and the current Coven CLI command surface.
4 min read
The user-facing command is coven. OpenCoven is the ecosystem and package namespace; Coven is the local runtime and command-line product.
Run coven with no arguments when you want the guided interactive shell. Use explicit subcommands when you want a scriptable or copy-paste path.
Command map
Every row below is a real top-level coven verb. Grouped reference pages cover subcommands, flags, and examples.
Core and sessions
| Command | Use it for |
|---|---|
coven | Open the interactive chat/shell when stdin/stdout are a terminal. |
coven chat | Open the interactive Coven UI explicitly (requires the coven-code engine). |
coven tui | Same as coven chat. See Interactive shell. |
coven doctor | Check local setup and print next steps; exits 1 when a blocking problem is found. |
coven config paths --json | Report resolved state, settings, engine, and local IPC paths without creating profile state. |
coven completions <shell> | Generate shell completions (bash, zsh, fish, elvish, powershell). |
coven daemon start | Start the local daemon process. |
coven daemon status | Inspect daemon pid, socket, and health state. |
coven daemon restart | Rebind the local socket after changes or stale state. |
coven daemon stop | Stop the local daemon. |
coven run codex "fix tests" | Launch a project-scoped Codex harness session. |
coven run claude "polish this UI" | Launch a project-scoped Claude Code harness session. |
coven sessions | Browse, attach, view, archive, summon, or sacrifice sessions. |
coven sessions --all | Include archived sessions. |
coven sessions --manage | Force the interactive session browser. |
coven sessions --plain | Print a plain table for scripts or copying. |
coven sessions --json | Print a JSON sessions array for clients. |
coven attach <session-id> | Replay/follow a session and forward input to live daemon sessions. |
coven summon <session-id> | Restore an archived session, then attach. |
coven archive <session-id> | Hide a completed session while preserving events. |
coven sacrifice <session-id> --yes | Permanently delete a non-running session and its event log. |
coven kill <session-id> | Kill a running session's process; its event log is kept. |
coven patch openclaw | Launch the guided repair flow for a registered repo. |
Observability and store maintenance
| Command | Use it for |
|---|---|
coven status | Show what's happening across your coven: daemon, sessions, familiars, skills, research, hub. |
coven familiars | List the familiar roster from ~/.coven/familiars.toml. |
coven skills | List installed skills from ~/.coven/skills/. |
coven memory | List familiar memory files from ~/.coven/memory/. |
coven research | Show the research loop log from ~/.coven/research/. |
coven calls | Show the Coven Calls delegation ledger. |
coven logs prune | Manage local log retention. |
coven vacuum | Repair and compact the local Coven session store. |
coven reset | Preview or recoverably reset selected local state categories; --apply moves them into a backup. |
coven pc | Diagnose and relieve macOS system pressure. See PC Diagnostics. |
All of these except coven pc are covered on Observability commands.
Hub and scheduling
| Command | Use it for |
|---|---|
coven hub | Inspect the multi-host hub control plane (read-only). |
coven scheduler | Inspect multi-host scheduler decisions and loop recovery (read-only). |
coven travel | Inspect travel-mode handoff state (read-only). |
coven executor | Stateless executor-node protocol commands, hub-dispatched over SSH or a private network. |
Covered on Hub and scheduling.
Engine and auth
| Command | Use it for |
|---|---|
coven engine | Manage the Coven engine (the interactive agent runtime). |
coven auth | Manage model provider credentials (Anthropic, Codex) — runs in the Coven engine. |
coven models | List available models — runs in the Coven engine. |
coven acp | Start the Agent Client Protocol server (stdio JSON-RPC) — runs in the Coven engine. |
coven code | Run any Coven engine subcommand directly (escape hatch). |
Covered on Engine and auth.
Repo workflow
| Command | Use it for |
|---|---|
coven wt | Create, list, diagnose, and prune Coven worktrees. |
coven claim | Manage TTL-bounded agent branch claims. |
coven maintenance | Fence new Coven writers while maintenance drains existing writers. |
coven hooks install | Install Coven Parallel Work Protocol git hooks. |
coven ward | Inspect and migrate Ward configuration. |
coven adapter | List and diagnose harness adapters. |
Covered on Repo workflow.
Configuration paths, reset, and color
Inspect path resolution without starting the daemon or creating state:
coven config paths --jsoncoven reset is preview-only unless --apply is passed. Select one or more
registered categories with --feature, inspect them with --list-features,
or use --all --apply. Applied resets move selected state to
$COVEN_HOME/reset-backups/; they do not delete project directories, contact
GitHub, or revoke provider credentials. Windows currently supports preview,
not --apply.
Every command accepts the global --color auto|always|never option. auto
honors NO_COLOR and CLICOLOR_FORCE.
What owns what
The CLI is a client and presentation layer. The daemon is the authority boundary for launches, cwd validation, session liveness, input forwarding, kill requests, and stored event state.
Use these references together:
- Install for package and source install paths.
- Doctor before opening issues or debugging a setup.
- Daemon commands for local process lifecycle.
- Run for project-scoped harness sessions.
- Sessions for attach, archive, summon, and sacrifice.
- Observability commands for status, familiars, skills, memory, research, calls, logs, and vacuum.
- Hub and scheduling for hub, scheduler, travel, and executor.
- Engine and auth for engine, auth, models, acp, and code.
- Repo workflow for wt, claim, hooks, ward, and adapter.
- Daemon lifecycle for the process and socket authority model.
- Sessions for status and archive semantics.
Bare prompt shortcut
When you pass text without a subcommand, Coven treats it as a Cast prompt:
coven "explain this repo in 5 bullets"Use the shortcut for quick interactive work. Use coven run <harness> <prompt> when you want an explicit harness and session record.
Last updated on