Commands
Every command below accepts --json (except explain) and prints a JSON
array of objects on success. corvee <command> --help shows runnable
examples for any of them. This page covers usage and flags only. Standalone,
checked-true (or not-yet-checked, or retracted) facts are not linked to
tasks by the schema (see Specification).
corvee
corvee: a single-machine, non-git-tracked, persistent, multi-agent-aware CLI task tracker and fact store.
Usage:
corvee [OPTIONS] COMMAND [ARGS]...
Options:
--version Show the corvee and schema version and exit.
--actor TEXT Stable identity for this invocation (e.g. agent:claude).
Overrides $CORVEE_ACTOR for every subcommand.
--session-id TEXT Per-session token stamped on events. Overrides
$CORVEE_SESSION_ID for every subcommand.
--help Show this message and exit.
brief
Session-start snapshot: what's claimed, what's ready, what's gone stale.
Combines task mine, task ready and task list --stale into one
read-only call.
Usage:
corvee brief [OPTIONS]
Options:
-s, --scope [local|global|all]
-j, --json
--help Show this message and exit.
completion
Print a shell completion script; eval its output to enable it.
Covers subcommand and flag names, click.Choice values (--state,
--priority, ...), and TASK-
Usage:
corvee completion [OPTIONS] {bash|zsh|fish}
Options:
--help Show this message and exit.
doctor
Project health: task/fact counts, staleness, and schema version.
Usage:
corvee doctor [OPTIONS]
Options:
-i, --stale TEXT [default: 4h]
-j, --json
--help Show this message and exit.
explain
Print a compact, agent-oriented cheat sheet.
Usage:
corvee explain [OPTIONS]
Options:
--help Show this message and exit.
export
Dump the whole project (or --scope global) as JSON.
Usage:
corvee export [OPTIONS]
Options:
-o, --output PATH
-s, --scope [local|global]
--help Show this message and exit.
fact
Standalone, checked-true claims, kept separate from tasks.
Lifecycle: a fact starts unverified. verify marks it verified with
proof and a timestamp; unverify moves it back. revise changes the
claim text and, if it was verified, resets it to unverified, since the
old proof said nothing about the new text. retract withdraws a fact
that should not have existed, dropping it out of the default list;
verify, unverify, and revise all still work on a retracted fact
and bring it back into the normal flow.
Usage:
corvee fact [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
add
Create a fact. Providing --proof verifies it immediately.
Usage:
corvee fact add [OPTIONS] CLAIM
Options:
-p, --proof TEXT
-g, --global File into the shared, machine-wide database instead of
this project's.
-j, --json
--help Show this message and exit.
delete
Permanently remove an already-retracted fact and its event history.
Usage:
corvee fact delete [OPTIONS] FACT_REF
Options:
-j, --json
--help Show this message and exit.
list
List facts. Default excludes retracted; --all includes them. Also runs as ls.
Usage:
corvee fact list [OPTIONS]
Options:
-S, --status [unverified|verified|retracted]
-d, --since TEXT Only facts updated within this duration.
-v, --verified-by TEXT
-i, --stale TEXT
-a, --all
-s, --scope [local|global|all]
-n, --limit INTEGER RANGE [x>=1]
-f, --fields TEXT
-j, --json
--help Show this message and exit.
list
List facts. Default excludes retracted; --all includes them. Also runs as ls.
Usage:
corvee fact list [OPTIONS]
Options:
-S, --status [unverified|verified|retracted]
-d, --since TEXT Only facts updated within this duration.
-v, --verified-by TEXT
-i, --stale TEXT
-a, --all
-s, --scope [local|global|all]
-n, --limit INTEGER RANGE [x>=1]
-f, --fields TEXT
-j, --json
--help Show this message and exit.
retract
Withdraw a fact; excluded from the default fact list.
Usage:
corvee fact retract [OPTIONS] FACT_REF
Options:
-r, --reason TEXT
-j, --json
--help Show this message and exit.
revise
Change a fact's claim text.
Usage:
corvee fact revise [OPTIONS] FACT_REF NEW_CLAIM
Options:
-j, --json
--help Show this message and exit.
search
Facts whose claim contains
Usage:
corvee fact search [OPTIONS] TEXT
Options:
-a, --all
-i, --include-proof Also match proof text, not just the claim.
-v, --verified-by TEXT
-s, --scope [local|global|all]
-n, --limit INTEGER RANGE [x>=1]
-f, --fields TEXT
-j, --json
--help Show this message and exit.
show
Full detail for one or more facts: claim, status, current proof, timeline.
Usage:
corvee fact show [OPTIONS] IDS...
Options:
-j, --json
--help Show this message and exit.
unverify
Mark a fact unverified again.
Usage:
corvee fact unverify [OPTIONS] FACT_REF
Options:
-m, --note TEXT
-j, --json
--help Show this message and exit.
verify
Mark a fact verified, recording proof and a timestamp.
Usage:
corvee fact verify [OPTIONS] FACT_REF
Options:
-p, --proof TEXT [required]
-j, --json
--help Show this message and exit.
import
Restore a dump into an empty project (or --scope global).
Usage:
corvee import [OPTIONS] FILE
Options:
-s, --scope [local|global]
-j, --json
--help Show this message and exit.
init
Create .corvee/config.toml. Appends to .gitignore if present, never creates.
Never touches AGENTS.md. Prints two pointer blocks instead: one for this project's own AGENTS.md, one for a global agents config such as ~/.claude/CLAUDE.md to apply across every project. Paste whichever fits.
Usage:
corvee init [OPTIONS]
Options:
-d, --db-path TEXT Where to store the database, relative to .corvee/. Only
used the first time a config is created.
-j, --json Emit a JSON report instead of text.
--help Show this message and exit.
mcp
Run corvee as an MCP server, for hosts that speak MCP natively but have no shell/exec tool (Claude Desktop, several IDE-integrated assistants).
A second, additive interface alongside the CLI, not a replacement for
it -- a harness that already shells out to corvee ... keeps doing so.
Usage:
corvee mcp [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
serve
Serve corvee's tasks and facts over the Model Context Protocol.
A long-lived process, unlike every other corvee command: it keeps running until the host closes its stdio pipes, serving one tool call at a time on a single dedicated worker thread. Run one server process per agent conversation -- a process shared across several conversations shares one actor identity for as long as it lives.
Usage:
corvee mcp serve [OPTIONS]
Options:
-p, --project-root DIRECTORY Explicit project directory to serve,
overriding auto-detection. Omit to auto-detect
from the server's own working directory, the
same lookup the CLI uses; falls back to global
scope only if nothing is found there.
-a, --actor TEXT Stable identity for this server process, read
once at startup. Falls back to a leading
global --actor flag, then $CORVEE_ACTOR, then
human:$USER.
-s, --session-id TEXT Default per-session token for this server
process, used by any tool call that omits its
own session_id argument. Falls back to a
leading global --session-id flag, then
$CORVEE_SESSION_ID, then a generated id unique
to this process.
--help Show this message and exit.
task
Work items: create, query, mutate, claim, label, link.
Usage:
corvee task [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
add
Create a task, or a whole batch from --from-file in one transaction.
Usage:
corvee task add [OPTIONS] [TITLE]
Options:
-d, --description TEXT
-t, --type [task|bug|feature|epic|chore|spike]
-p, --priority [low|medium|high|critical]
-l, --label TEXT Repeatable.
-P, --parent TEXT Link the new task as a child of this task.
-f, --from-file FILE Read a JSON array of task objects from PATH
instead of the TITLE argument and --descript
ion/--type/--priority/--label/--parent
options, and create all of them in one
transaction: if any item is invalid, none
are created. Each object supports the same
fields as the single-task options: "title"
and "description" (both required, non-
empty), "type", "priority", "label" (a list
of strings), and "parent" (an existing task
ref, same scope as this batch). --global
still applies to the whole file, the same
way it applies to a single `task add`.
-g, --global File into the shared, machine-wide database
instead of this project's.
-j, --json
--help Show this message and exit.
assign
Route one or more tasks to a specific actor, without claiming them.
Advisory only: not gated by an existing claim, and does not itself claim
the task. task mine surfaces it for the assigned actor once unclaimed.
Usage:
corvee task assign [OPTIONS] TASK_REFS...
Options:
-t, --to TEXT The actor this task is routed to. [required]
-j, --json
--help Show this message and exit.
claim
Claim one or more tasks for $CORVEE_ACTOR, or refresh a claim already held.
Usage:
corvee task claim [OPTIONS] TASK_REFS...
Options:
-f, --force Steal a claim held by another actor.
-j, --json
--help Show this message and exit.
claims
Actors currently holding live task claims, with a count and the oldest claimed_at.
Usage:
corvee task claims [OPTIONS]
Options:
-s, --scope [local|global|all]
-j, --json
--help Show this message and exit.
comment
Append a progress/handoff note (session stamped from CORVEE_SESSION_ID).
Usage:
corvee task comment [OPTIONS] TASK_REF TEXT
Options:
-j, --json
--help Show this message and exit.
label
Manage labels on one or more tasks; removals apply before additions.
Usage:
corvee task label [OPTIONS] TASK_REFS...
Options:
-a, --add TEXT Repeatable.
-r, --remove TEXT Repeatable.
-j, --json
--help Show this message and exit.
labels
List every label in the project with its task count.
Usage:
corvee task labels [OPTIONS]
Options:
-j, --json
--help Show this message and exit.
link
Relate two tasks, including hierarchy (cycle-checked for parent_of).
Usage:
corvee task link [OPTIONS] SOURCE_REF TARGET_REF
Options:
-r, --relation [blocks|relates_to|duplicates|parent_of]
[required]
-j, --json
--help Show this message and exit.
list
List tasks with full filtering and column projection. Also runs as ls.
Usage:
corvee task list [OPTIONS]
Options:
-S, --state [open|in_progress|blocked|review|done|cancelled]
-t, --type [task|bug|feature|epic|chore|spike]
-p, --priority [low|medium|high|critical]
-l, --label TEXT
-P, --parent TEXT
-b, --blocks TEXT Tasks that <id> blocks.
-B, --blocked-by TEXT Tasks that block <id>.
-r, --relates-to TEXT Tasks related to <id> (symmetric).
-c, --claimed-by TEXT
-u, --unclaimed
-A, --assigned-to TEXT
-i, --stale TEXT
-d, --since TEXT Only tasks updated within this duration.
-a, --all
-s, --scope [local|global|all]
-k, --after TEXT Cursor: only tasks after this id in the
fixed order.
-n, --limit INTEGER RANGE [x>=1]
-f, --fields TEXT
-j, --json
--help Show this message and exit.
list
List tasks with full filtering and column projection. Also runs as ls.
Usage:
corvee task list [OPTIONS]
Options:
-S, --state [open|in_progress|blocked|review|done|cancelled]
-t, --type [task|bug|feature|epic|chore|spike]
-p, --priority [low|medium|high|critical]
-l, --label TEXT
-P, --parent TEXT
-b, --blocks TEXT Tasks that <id> blocks.
-B, --blocked-by TEXT Tasks that block <id>.
-r, --relates-to TEXT Tasks related to <id> (symmetric).
-c, --claimed-by TEXT
-u, --unclaimed
-A, --assigned-to TEXT
-i, --stale TEXT
-d, --since TEXT Only tasks updated within this duration.
-a, --all
-s, --scope [local|global|all]
-k, --after TEXT Cursor: only tasks after this id in the
fixed order.
-n, --limit INTEGER RANGE [x>=1]
-f, --fields TEXT
-j, --json
--help Show this message and exit.
mine
Open tasks claimed by $CORVEE_ACTOR, each with its last comment.
The session-resume query.
Usage:
corvee task mine [OPTIONS]
Options:
-s, --scope [local|global|all]
-n, --limit INTEGER RANGE [x>=1]
-f, --fields TEXT
-j, --json
--help Show this message and exit.
purge
Permanently remove one or more already-cancelled, unlinked tasks and their event history, in one transaction.
Usage:
corvee task purge [OPTIONS] TASK_REFS...
Options:
-j, --json
--help Show this message and exit.
ready
Unclaimed open tasks with no open blocks predecessor — what can start right now.
Usage:
corvee task ready [OPTIONS]
Options:
-l, --label TEXT
-s, --scope [local|global|all]
-k, --after TEXT Cursor: only tasks after this id in the
fixed order.
-n, --limit INTEGER RANGE [x>=1]
-f, --fields TEXT
-j, --json
--help Show this message and exit.
search
Tasks whose title or description contains
Usage:
corvee task search [OPTIONS] TEXT
Options:
-a, --all
-i, --include-comments Also match comment bodies, not just
title/description.
-s, --scope [local|global|all]
-k, --after TEXT Cursor: only tasks after this id in the
fixed order.
-n, --limit INTEGER RANGE [x>=1]
-f, --fields TEXT
-j, --json
--help Show this message and exit.
show
Full detail for one or more tasks: description, labels, links, subtasks, timeline.
Usage:
corvee task show [OPTIONS] IDS...
Options:
-d, --since TEXT Only events newer than this.
-n, --no-events Drop the timeline; keep description/labels/links/subtasks.
-j, --json
--help Show this message and exit.
start
Claim one or more tasks and move them to in_progress, in one transaction.
Usage:
corvee task start [OPTIONS] TASK_REFS...
Options:
-f, --force Steal a claim held by another actor.
-j, --json
--help Show this message and exit.
tree
The full parent_of subtree rooted at
Usage:
corvee task tree [OPTIONS] REF
Options:
-j, --json
--help Show this message and exit.
unassign
Clear the assignment on one or more tasks.
Usage:
corvee task unassign [OPTIONS] TASK_REFS...
Options:
-j, --json
--help Show this message and exit.
unclaim
Release a claim on one or more tasks.
Usage:
corvee task unclaim [OPTIONS] TASK_REFS...
Options:
-f, --force Release a claim held by another actor.
-j, --json
--help Show this message and exit.
unlink
Remove a link.
Usage:
corvee task unlink [OPTIONS] SOURCE_REF TARGET_REF
Options:
-r, --relation [blocks|relates_to|duplicates|parent_of]
[required]
-j, --json
--help Show this message and exit.
update
Mutate one or more tasks in a single transaction.
Usage:
corvee task update [OPTIONS] TASK_REFS...
Options:
-S, --state [open|in_progress|blocked|review|done|cancelled]
-t, --type [task|bug|feature|epic|chore|spike]
-p, --priority [low|medium|high|critical]
-T, --title TEXT
-d, --description TEXT
-f, --force Override a claim held by another actor.
-c, --cascade Cancel every open descendant along with the
parent.
-j, --json
--help Show this message and exit.
Reading an id
Tasks are referenced externally as TASK-<n> (e.g. TASK-14) and facts
as FACT-<n> (e.g. FACT-7). Commands accept either the prefixed form or a
bare integer and normalize internally. A task command given a FACT-<n>
value (or a fact command given a TASK-<n> value) is rejected rather
than silently misread.
A task or fact filed with --global gets the TASK-GLOBAL-<n> /
FACT-GLOBAL-<n> form instead, its own id space in the shared global
database (~/.corvee/corvee.db) rather than the local project (see
Specification §3.3). Every command
that takes an id infers local vs. global from the id itself. Only add
needs the explicit --global flag, since there's no existing id to read
it from.
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Unexpected/internal error |
| 2 | Usage or validation error |
| 3 | Task or fact not found |
| 4 | Claim conflict: the task is held by another actor |
| 5 | Guard violation: open children, a parent_of cycle, a rejected state transition, claiming an already-terminal task, fact delete on a non-retracted fact, linking across the local/global scope split |
| 6 | Project/config problem: no or unreadable .corvee/config.toml, a database file that cannot be opened or written, or a schema newer than this binary supports |
For the exact JSON shapes, filter semantics, and every edge case, see the Specification. This page is a summary, not the contract.