Commands Reference

Complete CLI surface. Every command outputs stable JSON to stdout. Errors go to stderr with exit code 2.

Global flags

These apply before any subcommand:

FlagTypeWhat it does
--debugbool

Print database operations alongside normal output

--db <path>string

Path to the kanban database (default: .kanban/kanban.db)

task

Core operations for creating, claiming, tracking, and completing work.

CommandWhoWhat it does
task dispatch --title --role [--project] [--priority] [--depends-on]any

Create a new task in TODO state. --depends-on accepts comma-separated task IDs.

task claim <id> --agentworker

Claim a specific task by ID. Transfers can use --transfer --to <agent>.

task claim-next --agent --role [--count N] [--project] [--respect-deps]worker, reviewer

Atomically claim highest-priority available task(s). Reclaims expired leases. --count N claims multiple in one transaction.

task log-progress <id> --agent --note [--type]worker

Log progress and renew the 15-minute lease. --type can be PROGRESS, ERROR, DECISION, REVIEW, or SYSTEM.

task extend-lease <id> --agent [--minutes]worker

Renew lease without logging progress. For long tasks >15m.

task block <id> --agent --reasonworker

Mark blocked and clear the current lease.

task complete <id> --agent [--review]worker

Mark task as done (default) or submit for review with --review flag.

task view <id> [--notes] [--history]all

Full task detail with timestamps, notes, and audit trail.

task search [--status] [--role] [--agent] [--project]manager

Filter task list. Shows lease_until for IN_PROGRESS tasks.

task stats [--status] [--role]manager

Aggregate task statistics by status or role.

task approve <id> --agent [--note]reviewer

Move IN_REVIEW to DONE with optional review note.

task approve --all --agent [--project]reviewer

Batch approve all IN_REVIEW tasks.

task reject <id> --agent --reasonreviewer

Return IN_REVIEW to TODO with context.

batch

Atomic multi-task operations. All changes within one command happen in a single transaction.

CommandWhoWhat it does
batch claim --agent --role [--count N] [--project] [--respect-deps]worker

Claim N tasks atomically in one transaction.

batch complete --ids <id1,id2> --agent [--to-review]worker

Complete multiple tasks in one transaction. Use --to-review to submit for review.

batch set-priority --ids <id1,id2> --prioritymanager

Bulk priority update.

batch set-project --ids <id1,id2> --projectmanager

Bulk project label update.

plan

Plan parsing, proposal generation, and structural validation.

CommandWhoWhat it does
plan lintmanager

Check plan.md for dependency cycles, unknown dependencies, and structural issues.

plan create <file>manager

3-pass LLM extraction: read spec, write proposal, write checked proposal.

plan approvemanager

Read checked proposal and dispatch each approved task.

init

Scaffold the kanban project structure.

CommandWhoWhat it does
init [--harness generic|pi|claude] [--plan plan.md] [--dir <path>]setup

Create .kanban/ directory, database, agent definitions, and skill files. --harness selects agent format.

re-initsetup

Re-scaffold agent files without touching the database.

Utility commands

CommandWhoWhat it does
events [--task <id>]all

View the event log. Filter by task ID for targeted history.

skill listall

List all available protocol skills with descriptions.

skill view <name>all

Show full skill definition.

prune [--before <duration>] [--dry-run]ops

Clean expired events and notes. Use --dry-run to preview.

status [--burndown] [--project]all

Board status: counts by status or progress bars per project.

Output format

Every command outputs a JSON object to stdout. Empty results return {}.

example
# Successful operation
$ kanban task claim-next --agent alice --role worker
{"id":"TASK-1","title":"Set up auth","status":"IN_PROGRESS"}

# Empty result (no work available)
$ kanban task claim-next --agent bob --role worker
{}

# Error
$ kanban task approve TASK-1 --agent bob
{"error":"task is not IN_REVIEW (current state: TODO, expected: IN_REVIEW)"}
# (exit code 2)