CLI Reference
First-class reference for the coven command and the current Coven CLI command surface.
5 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.
Find the right command
Coven's public help is progressive: the default view stays concise, command help goes deep on one path, and the complete catalog is opt-in.
coven help # concise core-command guide
coven help run # help for one command
coven help sessions show # help for a nested command
coven run --help # equivalent command-specific form
coven help --all # every public command, grouped by task
coven help --all --json # machine-readable grouped catalogThe JSON catalog has an explicit schema version and is the preferred discovery surface for tools that need the current public command tree. Hidden implementation commands are not exported. Every help route accepts --color auto|always|never; auto honors NO_COLOR and CLICOLOR_FORCE.
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 help | Show concise help; add <command>, --all, or --all --json for deeper discovery. |
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 setup codex | Run Codex's provider-owned login with explicit consent and direct terminal access. |
coven setup claude --verify | Run Claude Code login, then separately request consent for bounded provider verification. |
coven setup copilot --verify-only | Skip login and run only the consented Copilot verification turn. |
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. |
Use Provider setup for consent, verification, and report semantics.
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. Provider login and verification remain provider-owned processes launched only after explicit consent.
Use these references together:
- Install for package and source install paths.
- Doctor before opening issues or debugging a setup.
- Provider setup for consent-gated login and bounded verification.
- 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.
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.
