CLI How-To Guide

This page shows worked, copy-pasteable invocations for the core DRAFT→BUILD→SETTLE loop commands. It assumes the loop, gates, profiles, and tiers are already familiar — if not, read docs/concepts.md first.

The SPEC stage and the strategic-intelligence commands (recommendation / assumption / decision / intelligence / inspect / recommend / milestone, plus spec and context) are documented in docs/reference/commands.md, which also carries the exhaustive option lists (every flag and its default).

Install: npm install -g @thomas-powers-jr/cadence-core provides the cadence command used in every example below (requires Node ≥ 22).

---

Table of contents

• init — set up a project
• Draft workflow
  • draft new — scaffold a DRAFT
  • draft check — coherence-check before approve
  • draft approve — enter BUILD
• build task — record task outcomes
  • Shortcut commands: done / block / needs-context
• settle run — close the loop
  • Mode flags
  • Bypass flags
• status — inspect loop state
• progress — next recommended action
• config — read and write config
• Hand the loop to your AI agent
• Single-commit convention in practice

---

init — set up a project

Scaffold a .cadence/ directory in the current repo root:

cadence init --name "my-project" --profile team --gate-profile standard

Options used above:

Option	Purpose
--name <project>	Project name embedded in PROJECT.md
--profile <preset>	solo / team / production — sets the starting config preset
--gate-profile <p>	strict / standard / auto — overrides the gate profile CADENCE would suggest from git history
--host <host>	claude / codex — wire a host during init; codex also writes AGENTS.md

For a first Codex run, use the full bootstrap before launching Codex:

cadence init --host codex

The plain Codex host installer only writes .codex/hooks.json and global prompt files. --host codex also creates the project .cadence/ state and the managed AGENTS.md instructions that Codex reads at session start.

To regenerate only a managed agent-instruction block (e.g. after updating CADENCE) on an already-initialized repo:

cadence init --claude-md
cadence init --agents-md

After init, commit .cadence/ before starting any phase work.

---

Draft workflow

A phase begins in IDLE and advances to BUILD only after a DRAFT is approved.

draft new — scaffold a DRAFT

cadence draft new 01-retry 1 --title "Add retry logic"

Arguments: <phase> <task-num>. The draft id is derived as the first two characters of the phase plus the zero-padded task number, so this creates:

.cadence/phases/01-retry/01-01-DRAFT.md

Open the file and replace the template placeholders:

• Frontmatter: phase / id / tier (quick-fix / standard / complex) / status
• ## Objective — one-sentence description
• ## Acceptance Criteria — at least one ### AC-N block with Given / When / Then
• ## Tasks — ### T1 blocks with files / action / verify / done: AC-N
• ## Boundaries — what the AI must not change

For a first real task, use a template to avoid starting from a blank scaffold:

cadence draft new --title "Fix login timeout" --template bugfix
cadence draft new --title "Add CSV export" --template feature
cadence draft new --title "Split billing service" --template refactor

Templates generate editable Objective, AC, Task, and Boundary sections. They are starting points for a human or agent to refine; they do not prove the work is correct. The normal approve and settle gates still decide whether the phase can close.

For a complex phase with an explicit tier:

cadence draft new 02-auth 3 --title "Refactor auth" --tier complex

draft check — coherence-check before approve

Run the structural coherence check before committing to approve:

cadence draft check .cadence/phases/01-retry/01-01-DRAFT.md

The check validates tier vs task/file counts, AC format, and loop position. Address any issues reported before proceeding to approve.

draft approve — enter BUILD

cadence draft approve 01-retry 1

What happens at approve (depending on the gate set):

• approve gate: interactive Y/N prompt (TTY) or requires --no-approve flag
• plan-review gate: AI plan-review agent runs; pass=false refuses approve

For non-TTY environments (CI, hooks) when the approve gate is active:

cadence draft approve 01-retry 1 --no-approve

To proceed past a failing plan-review (findings are still printed):

cadence draft approve 01-retry 1 --allow-plan-review-failure

To override the auto × complex soft cap:

cadence draft approve 01-retry 1 --allow-auto-complex

After approve, the loop is in BUILD and task recording can begin.

---

build task — record task outcomes

cadence build task T1 --status=DONE

cadence build task T2 --status=DONE --notes "Added retry with exponential backoff"

Valid --status values: DONE | DONE_WITH_CONCERNS | NEEDS_CONTEXT | BLOCKED

When the per-task-verify gate is active (e.g. strict × standard), the verifier runs on --status=DONE before accepting the status write. A refuse verdict blocks the record unless bypassed:

cadence build task T1 --status=DONE --allow-per-task-failure

Shortcut commands: done / block / needs-context

Three convenience shortcuts reduce typing for the most common statuses:

# Mark DONE
cadence done T1
cadence done T1 --notes "implemented with caching"

# Mark BLOCKED
cadence block T2 --notes "waiting for API spec"

# Mark NEEDS_CONTEXT
cadence needs-context T3 --notes "unclear which endpoint to use"

Carry-forward: block and needs-context accept any string as <id> without validating it against the list of tasks declared in the active DRAFT. If you pass a misspelled or non-existent task id, the engine writes the record under that id and settle’s structural gate will detect the inconsistency. Double-check task ids against the DRAFT before running these two shortcuts. done is unaffected — it is a true alias for build task (phase 281) and refuses an undeclared id outright (exit 2), recording nothing.

---

settle run — close the loop

settle run closes the phase, runs the gate set, writes SUMMARY.md + SUMMARY.json, and returns the loop to IDLE.

Mode flags

Manual AC verdicts (always available):

cadence settle run --ac AC-1=pass --ac AC-2=pass
cadence settle run --ac AC-1=pass --ac AC-2=fail:tests-missing

Auto mode — derive AC verdicts from task statuses:

cadence settle run --auto

Blocks on incomplete or failed ACs. To settle past them anyway:

cadence settle run --auto --force

Deep verify — run the independent AI verifier against each AC:

cadence settle run --deep

The provider comes from config.verifier. See docs/providers.md for setup.

Interactive — walk each AC and enter a verdict at the prompt:

cadence settle run --interactive

Requires a TTY. In non-TTY environments, use --no-interactive to skip the gate when the active profile would normally enforce it.

Bypass flags

Flag	Gate bypassed	When to use
--auto	—	Derive verdicts from task statuses instead of providing them manually
--force	deep-verify, interactive-verdict, code-review, security-audit (all)	Force settle past any gate failure
--allow-stale-draft	draft-read	DRAFT.md was edited after approve
--allow-open-tasks	structural-verifier	A task is still PENDING / IN_PROGRESS
--allow-failing-build	verification.testCommand exit	Settle past a non-zero build/test exit
--allow-missing-coverage	test-coverage	AC token not found in any test file
--allow-verifier-failure	deep-verify transport errors	Record failure but don’t refuse
--allow-code-review-failure	code-review HIGH-severity findings	Record findings but settle anyway
--allow-security-audit-failure	security-audit CRITICAL findings	Record findings but settle anyway
--allow-skill-audit-miss	skill-audit	Required skills were not invoked; emit a warn anomaly and settle anyway
--no-interactive	interactive-verdict	Opt out of the interactive gate (profile-level bypass)
--allow-auto-complex	auto × complex soft cap	Override the soft cap

For a full explanation of which gates fire in which profile × tier cell, see docs/concepts.md — Gate matrix.

---

status — inspect loop state

Show full loop context: phase, draft, tasks, ACs, and next recommended action:

cadence status

Machine-readable JSON output (useful in scripts):

cadence status --json

List recorded anomaly events:

cadence status anomalies

---

progress — next recommended action

Print a single recommended next action for the current loop position:

cadence progress

Useful as a quick orientation command after picking up a session. The host adapter’s /cadence-progress slash command calls this under the hood.

---

config — read and write config

Print a config value by dotted path:

cadence config get verifier.provider
cadence config get perTaskVerifier.model

Update a config value (validated against the schema):

cadence config set verifier.provider anthropic
cadence config set codeReview.provider local

Diagnose config conflicts (e.g. provider set without required env vars):

cadence config doctor

The full list of config fields and presets is in docs/reference/config.md.

---

mcp serve — drive the loop from an MCP host

Run the engine as a local MCP server over stdio, so any MCP-capable host (Claude Desktop, Cursor, agents) can call the loop as tools:

cadence mcp serve            # operate on the current working directory
cadence mcp serve --repo /path/to/project

It’s a local subprocess, not a network service — the host launches it and talks over stdin/stdout. It advertises 10 tools wrapping the same commands documented above (cadence_progress/status/recommend read; cadence_draft_new/ draft_check/draft_approve/build_task/settle/spec_new/spec_approve write). Command-boundary gates run exactly as on the CLI; ambient edit-time gates require host hooks and are not available over MCP. Setup and the full tool table: docs/mcp.md.

---

Hand the loop to your AI agent

cadence agent-prompt --goal "fix the login timeout"

Prints a ready-to-paste prompt for your coding agent. Without --goal it prints a <your goal> placeholder. The same block also appears at the end of cadence init.

---

Single-commit convention in practice

A completed phase produces exactly one commit. Here is what that looks like for a phase called P05 / T2:

# 1. Do the work. Record task outcomes as you go.
cadence done T1
cadence done T2 --notes "added edge-case test"

# 2. Settle the loop. This writes SUMMARY.* and resets state to IDLE.
cadence settle run --auto

# 3. One commit: source changes + phase artifacts together.
git add src/ tests/ docs/ .cadence/
git commit -m "feat: add retry logic with exponential backoff (P05/T2)"

Why one commit? The gates already re-verified the work in step 2 — there’s nothing left to prove by splitting artifacts into a second commit. One commit is the single atomic record of both the code change and the gate outcomes/AC verdicts that backed it, keeping audit straightforward without adding a step.

For the conceptual rationale, see docs/concepts.md — Single-commit convention.

---

See also: docs/concepts.md — loop, gates, profiles, tiers | docs/reference/commands.md — exhaustive option lists | docs/claude-code.md — Claude Code host adapter how-to | docs/mcp.md — drive the loop from any MCP host | docs/providers.md — provider setup