CLI reference

Every command, flag and example, generated from the binary rather than written about it.

Generated from kadence 0.11.0, the version on npm — every command, flag and example below came out of that binary rather than being described from memory. The contract an agent reads is the same file: kadence schema --json.

Setting up

kadence init needs a git repository and writes .kadence/ plus the agent instruction files. Everything below needs that directory, except kadence schema, which describes the tool rather than your project and answers anywhere.

Since 0.9, run by a person at a terminal with no flag, init is a guided setup: Coda says what it found — the agents in use, an ADR folder — asks one question with a recommended answer, offers the ADRs as decisions with a preview, and shows what a teammate's agent will see when someone proposes what you ruled out. Nothing is written before the answer, Ctrl-C keeps what is written, and running it again is a checkup. An agent, a script, CI or any flag gets no question at all, and the output ends with what an agent should do next. KADENCE_INTERACTIVE=0 turns the questions off.

kadence init

Set up kadence in this repository

Usage:  kadence init

Options:
  --no-hooks            Leave .claude/settings.json alone: no prime at session start, no journal search on each prompt (default: true)
  --hooks               Accepted for older scripts; the hooks are on by default now
  --hooks-for <agents>  Also write hooks for: codex, cursor, copilot (comma-separated). Without it, only for those already in use
  -h, --help            Display this message

Examples:
  kadence init
  kadence init --no-hooks
  kadence init --hooks-for codex,cursor

Starting a session

These two are what an agent runs before it does anything else: the state that moves, and the work that can be started. The state that does not move already lives in AGENTS.md, where init put it.

kadence prime

Everything a session needs before it starts. Short by design

Usage:  kadence prime

Options:
  --json      Machine-readable output for agents
  -h, --help  Display this message

Examples:
  kadence prime
  kadence prime --json

Held to 40 lines and 3 KB by a test in the product, because it enters an agent's context on every session. Long context files were measured to cost more than they return; this one carries what changes and points at the rest. Since 0.5 it does not open with "No active sprint." when there is none, and with no decision in force it spends one line on how to record one.

kadence ready

What can be started right now: open, unblocked, unclaimed

Usage:  kadence ready

Options:
  -a, --assignee <who>  Only this person; "me" for yourself
  --limit <n>           At most this many tasks
  --json                Machine-readable output for agents
  -h, --help            Display this message

Examples:
  kadence ready
  kadence ready --assignee me --json

The work and its reasons

kadence task

Usage:  kadence task [action] [arg] [value] [extra]

Options:
  --title <text>            New title (for edit)
  -d, --description <text>  Full description; use quotes for multiple lines
  --type <type>             Type: task | bug | story | epic
  --priority <level>        Priority: low | normal | high | urgent
  -a, --assignee <who>      Assignee, e.g. dev@example.com
  --label <name>            Label; repeat the flag for several. On edit, the set becomes exactly this
  --add-label <name>        Add one label, leaving the rest; repeat for several
  --remove-label <name>     Remove one label, leaving the rest; repeat for several
  --estimate <points>       Estimate in points, a positive number
  --due <date>              Due date, YYYY-MM-DD; empty string clears it
  --status <status>         Filter by status: backlog | todo | in_progress | blocked | in_review | done | cancelled
  --search <text>           Words in title, description, criteria and comments, matched as kadence search matches them; most relevant first unless --sort
  --milestone <ref>         list: only the tasks in this milestone — MS-N or its name
  --why <text>              ac waive: why the criterion does not apply to this task
  --overdue                 Only tasks past their due date
  --due-before <date>       Only tasks due before YYYY-MM-DD
  --sort <key>              Sort by: created | priority | due | estimate
  --tree                    Show parent/child structure
  --branch                  Only the work this branch introduced
  --base <name>             What --branch compares against; main by default
  --parent <task>           Parent task, e.g. KAD-1 (use "none" to detach)
  --template <name>         Pre-fill fields from a saved template
  --no-dod                  Skip the board's definition of done for this task (default: true)
  --ac <text>               add: an acceptance criterion; repeat for more
  --fields <list>           JSON only: comma-separated task fields to return
  --limit <n>               list: at most this many; 0 for all of them
  --offset <n>              list: start the page here; use with --limit
  --json                    Machine-readable output for agents
  -h, --help                Display this message

Examples:
  kadence task add "Fix login" -d "Broken since 2.3" --type bug --priority high --estimate 3
  kadence task list --status in_progress --sort priority
  kadence task list --search cookie --overdue
  kadence task list --assignee me --label auth
  kadence task list --tree
  kadence task list --branch            what this branch is about
  kadence task list --branch --base release/1.0
  kadence task list --json --fields id,label,status
  kadence task move KAD-1,KAD-2,KAD-3 done     bulk: all or nothing
  kadence task add "Login form" --parent KAD-1   KAD-1 can be an epic
  kadence task add "Login form" --ac "rejects a bad password" --ac "remembers the email"
  kadence task claim                            take the top of `kadence ready`
  kadence task claim KAD-1
  kadence task release KAD-1
  kadence task ac add KAD-1 "tests green"
  kadence task ac check KAD-1 1
  kadence task ac list KAD-1
  kadence task doc add KAD-1 docs/design.md   create it and link it
  kadence task parent KAD-2 KAD-1
  kadence task block KAD-2 KAD-1               KAD-2 waits for KAD-1
  kadence task unblock KAD-2 KAD-1
  kadence task log KAD-1 2h                     also 90m, or -30m to correct
  kadence task add "Crash on save" --template bug
  kadence task show KAD-1
  kadence task move KAD-1 done
  kadence task edit KAD-1 --priority urgent --due 2026-09-30
  kadence task edit KAD-1                      opens $EDITOR for the description
  kadence task comment KAD-1 "Needs review"
  kadence task assign KAD-1 dev@example.com     (use "none" to unassign)
  kadence task cancel KAD-1                    keeps it in history
  kadence task delete KAD-1                    drops it from the board

claim has no lock behind it. Two machines can each claim a task before either pushes; after the merge the earliest claim holds and the task reads contested under both names. Rejecting the later one would make the owner depend on which branch merged first, which is the same reason a dependency cycle is reported rather than refused.

Moving a task to done with unchecked acceptance criteria warns and proceeds. The board marks it. A tool that refuses would be a tool people work around.

--label sets the whole set; --add-label and --remove-label change one and leave the rest. The second pair exists because the first loses a label when two branches add different ones — measured, and fixed in 0.4 by moving labels as deltas.

Bulk is all or nothing: kadence task move KAD-1,KAD-2 done either moves both or changes nothing, so a typo cannot leave half a board.

kadence decision

Decisions: add | list | show — the why behind the work

Usage:  kadence decision [action] [arg]

Options:
  --why <text>        Why this was chosen. Required — without it this is a changelog line
  --rejected <text>   The alternative that was turned down
  --task <ref>        The task this decision came out of
  --supersedes <ref>  The decision this one replaces
  --doc <path>        A document that carries the detail; repeat for several
  --limit <n>         list: at most this many decisions; 0 for all of them
  --offset <n>        list: start the page here
  --all               Include superseded decisions, hidden by default
  --json              Machine-readable output for agents
  -h, --help          Display this message

Examples:
  kadence decision add "Use ULIDs" --why "Clocks disagree between machines"
  kadence decision add "Use Avro" --why "..." --supersedes DEC-1
  kadence decision list --json

--why is required. Without it the record says only what changed, and git already says that.

Superseding is one event. --supersedes writes a single record and the backward link is derived while folding, so the two directions cannot fall out of step — the failure that makes a reversed decision keep looking current in a file-based tool, where it takes two edits and people reliably make one.

kadence note

Record something learned; note list and note show <ULID> read them back

Usage:  kadence note [text] [id]

Options:
  --task <ref>  The task it came out of
  --limit <n>   At most this many, newest first; 0 for all of them
  --offset <n>  list: start the page here
  --json        Machine-readable output for agents
  -h, --help    Display this message

Examples:
  kadence note "Tests need a git identity"
  kadence note "The redirect drops the cookie" --task KAD-1
  kadence note list --limit 5
  kadence note show 01K5...

A note is something learned. When there was a choice and something was turned down, that is a decision instead — the help says so when you reach for the wrong one.

kadence doc

Documentation: add | edit | show | list | link — kept in the journal, not in files

Usage:  kadence doc [action] [arg] [arg2]

Options:
  --body <text>   The text
  --stdin         Read the text from standard input — for text too long for an argument
  --file <path>   Read the text from a file; the file is not kept or linked
  --title <text>  A new title, for edit
  --task <ref>    The task this explains (add), or narrow the list to one task
  --limit <n>     list: at most this many documents; 0 for all of them
  --offset <n>    list: start the page here
  --json          Machine-readable output for agents
  -h, --help      Display this message

Examples:
  kadence doc add "Auth" --body "How login works." --task KAD-1
  kadence doc edit DOC-1 --file draft.txt
  kadence doc edit DOC-1                 opens $EDITOR at a terminal
  kadence doc show DOC-1 --json
  kadence doc link DOC-1 KAD-2

Documentation is an entity in the journal since 0.6, not a file beside it: DOC-N, written and revised as doc.written events. A note records a moment and never changes; a document is the current account of how something works, and the reader wants the latest.

Every revision names the revisions it was written on top of. Two people revising the same version leave a conflict that is reported and settled by writing text — never a silent overwrite, and never a winner picked by whichever branch merged first.

Agents reach it without a search term: task show carries the documents linked to a task and prime names the documentation of the work you hold, both without bodies. One body arrives only when something asks for it.

kadence task doc is still there for linking a markdown file that already exists. It records the link, which is the part git cannot express.

Looking at it

kadence board

Kanban board in the terminal; "config" edits it, "export" writes a snapshot

Usage:  kadence board [action]

Options:
  --fields <list>       JSON only: comma-separated task fields to return
  --statuses <list>     Comma-separated columns, e.g. "todo,doing,done"
  --dod <list>          Criteria every new task starts with, e.g. "tests green,docs updated"
  --started <status>    The column where work counts as started; cycle time is measured from it
  --history             JSON only: every task in full, with its history and comments
  --summary             JSON only: what --json returns already; kept so older calls still work
  --html                export: one self-contained HTML file, no server and no network
  --md                  export: markdown for a README or a pull request
  --readme              export: update the section between markers in README.md
  --file <path>         export: where to write it
  -a, --assignee <who>  Only this person's tasks; "me" means you
  --sprint              Only tasks in the active sprint
  --limit <n>           At most this many tasks across the board; 0 for all of them
  --offset <n>          Start the page here, counted across the columns
  --json                Machine-readable output for agents
  -h, --help            Display this message

Examples:
  kadence board
  kadence board --assignee me --sprint
  kadence board --json --fields label,status,assignee
  kadence board --json                  the state of each task, without the history
  kadence board --json --history        every task in full
  kadence board config
  kadence board config --statuses "todo,doing,review,done"
  kadence board config --dod "tests green,docs updated"
  kadence board config --started doing        where cycle time starts counting
  kadence board export --html
  kadence board export --md --readme

Since 0.9, board --json returns the state of each task — the fields --summary selected — and leaves out the history and comments that grow with how long the work took. --history returns every task in full; --summary still works and answers the same as no flag.

board export writes a file: one self-contained HTML page, or markdown for a README or a pull request. There is no server and no port, which is what lets a browser view exist at all in a tool that promises none.

kadence ui

Interactive kanban board

Usage:  kadence ui

Options:
  -h, --help  Display this message

Examples:
  kadence ui

The contract

kadence schema

The machine-readable --json contract, for agents

Usage:  kadence schema

Options:
  --json      Machine-readable output for agents
  -h, --help  Display this message

Examples:
  kadence schema --json

Read this instead of guessing. It lists every command, the fields you can rely on, and every error code, and it works outside a repository so an agent can read it before init. The contract is deliberately narrower than the output: fields kadence emits but does not list may still change.

Planning

kadence sprint

Usage:  kadence sprint [action] [name]

Options:
  --sprint <name>           Which sprint to add to; defaults to the active one
  --name <name>             New name (for edit)
  -d, --description <text>  Sprint description (for edit)
  --start <date>            Start date, YYYY-MM-DD
  --end <date>              End date, YYYY-MM-DD
  --json                    Machine-readable output for agents
  -h, --help                Display this message

Examples:
  kadence sprint create "Sprint 1"    first one starts right away
  kadence sprint create "Sprint 2"    later ones are planned
  kadence sprint add KAD-1 --sprint "Sprint 2"
  kadence sprint start                starts the next planned sprint
  kadence sprint edit --start 2026-09-01 --end 2026-09-14
  kadence sprint edit "Sprint 2" --name "Sprint 2: auth"
  kadence sprint burndown            chart from the journal, any day
  kadence sprint close                closes the active one, reports velocity

kadence milestone

Milestones: create | add | list | close — grouping by outcome

Usage:  kadence milestone [action] [arg]

Options:
  --due <date>       Target date, YYYY-MM-DD
  --milestone <ref>  Which milestone, by MS-N or name
  --all              Include closed milestones, hidden by default
  --json             Machine-readable output for agents
  -h, --help         Display this message

Examples:
  kadence milestone create "1.0" --due 2026-12-01
  kadence milestone add KAD-1 --milestone 1.0
  kadence milestone list --json
  kadence milestone close 1.0

kadence template

Task templates: save | list | delete

Usage:  kadence template [action] [name]

Options:
  -d, --description <text>  Default description
  --type <type>             Default type
  --priority <level>        Default priority
  -a, --assignee <who>      Default assignee
  --label <name>            Default label; repeat for several
  --estimate <points>       Default estimate
  --json                    Machine-readable output for agents
  -h, --help                Display this message

Examples:
  kadence template save bug --type bug --priority high --label triage
  kadence template list

Reading the project

kadence report

Usage:  kadence report [name]

Options:
  --list           Name every report and what each one answers
  --since <days>   flow, cfd, attention: window ending today, in calendar days (default 30d)
  --sprint <name>  burndown, burnup: a sprint by name, rather than the active one
  --by-status      flow: time in each status and flow efficiency, instead of the usual report
  --html           Write one self-contained page instead of printing; charts included, no network
  --file <path>    html: where to write it (default kadence-<report>.html)
  --json           Machine-readable output for agents
  -h, --help       Display this message

Examples:
  kadence report --list               every report, and what it answers
  kadence report flow                 cycle time, throughput, aging work
  kadence report flow --since 90d
  kadence report cfd                  tasks per column, per day
  kadence report attention            work in flight that nobody is moving
  kadence report burndown             the active sprint against an even burn
  kadence report velocity             committed against finished, sprint by sprint
  kadence report workload             who is carrying what right now
  kadence report flow --html          the same numbers as a page, with charts
  kadence report cfd --html --file docs/cfd.html
  kadence report flow --by-status     where the time went, column by column

kadence report --list names all six and what each answers, attention first. report <name> --html writes one self-contained page with inline SVG charts that asks the network for nothing, and every chart is followed by the rows it was drawn from. Every report is a fold over events the journal already holds. None of them adds an event type or a field, and none of them is written down — attention costs half a millisecond over ten thousand events on top of the fold.

kadence stats

Where the project stands: counts, blockers, contested claims, velocity

Usage:  kadence stats

Options:
  --json      Machine-readable output for agents
  -h, --help  Display this message

Examples:
  kadence stats

Maintenance

kadence doctor

Rebuild the cache from the events, check the journal reads cleanly, report what it found

Usage:  kadence doctor

Options:
  --json      Machine-readable output for agents
  -h, --help  Display this message

Examples:
  kadence doctor
  kadence doctor --json

Folds the whole journal whatever the cache says, writes the result to .kadence/state.json, and reports how many events read, which files did not, whether the cache it found had agreed with the journal, and what the fold surfaces — contested claims, cycles, columns not in the board. It never touches an event. A file that cannot be read exits 1 with journal_damaged; a surfaced conflict is not an error, because keeping both sides is the journal doing its job.

kadence compact

Fold old months into one file each; cold start on a long journal drops from ~200 ms to ~20 ms

Usage:  kadence compact

Options:
  --keep-months <n>  Months to keep as separate files, counting this one (default 2)
  --dry-run          Say what would be archived and write nothing
  --json             Machine-readable output for agents
  -h, --help         Display this message

Examples:
  kadence compact --dry-run
  kadence compact --keep-months 3

Only the shape on disk changes. The same events fold to the same state afterwards, which is the property the whole product rests on, and the archive is merged rather than replaced — a branch that compacts, merges and then delivers one more event for that month used to lose the archive.

kadence completion

Shell completion; "install" writes it where your shell looks

Usage:  kadence completion [action]

Options:
  --shell <name>  Shell: zsh | bash | fish; detected from $SHELL by default
  --force         Overwrite a completion file kadence did not write
  --json          Machine-readable output for agents
  -h, --help      Display this message

Examples:
  kadence completion            print the script
  kadence completion install --shell zsh

Writes the script where your shell looks for it, and says what it wrote. Without install it prints the script instead, for you to place yourself.

Everything else

kadence search

Find it across tasks, decisions, notes and documents

Usage:  kadence search <query>

Options:
  --kind <list>      Narrow to: task | decision | note | doc | sprint | milestone; comma-separated
  --limit <n>        At most this many passages
  --all              Include superseded decisions, left out by default
  --also <phrasing>  The same question in other words; repeat for 2-3. Fused into one answer
  --json             Machine-readable output for agents
  -h, --help         Display this message

Examples:
  kadence search "why are events append-only"
  kadence search "where is the website hosted" --also "landing page" --also "GitHub Pages"
  kadence search "cookie redirect" --kind task,note
  kadence search "ordering between machines" --json

kadence hook

For agent hooks: prompt reads a UserPromptSubmit payload; cursor-session and copilot-session print prime as JSON; log shows what they added to the last session

Usage:  kadence hook <event>

Options:
  --json      log: machine-readable output
  -h, --help  Display this message

Examples:
  echo '{"prompt":"why are events append-only"}' | kadence hook prompt
  kadence hook cursor-session
  kadence hook log            what kadence put into your agent's context, and its size

Everywhere

--json        machine-readable output; stdout is JSON and nothing else
--help        this, for any command

Exit codes: 0 success, 1 runtime error — the command understood you and could not comply, 2 bad arguments — nothing was attempted.

Environment:

KADENCE_SOURCE   Set to "agent" so events record agent authorship. Without it an event counts as human — we do not guess.
KADENCE_ACTOR    Who holds a claim, when that is not your git email: one of several agents a person runs, e.g. "you@example.com#agent-2". Without it, an agent (KADENCE_SOURCE=agent) in a linked git worktree claims as "email#<worktree>". Events are still authored by the git email.
NO_COLOR         Any value disables colour.
KADENCE_INTERACTIVE "0" means `init` never asks a question; "1" lets it ask past an agent marker. It never asks in a pipe, with a flag, in CI, or where AI_AGENT, CLAUDECODE, CURSOR_AGENT, CODEX_SANDBOX or GEMINI_CLI is set.

The error codes a --json failure can carry, and the fields on a task you can rely on, are written for agents.

On this page