Commands
Every carol command in v0.1.22: one line on what it does, its flags, and an example.
Carol v0.1.22
Run Carol from the repository root. carol --help and carol <command> --help print the same flags.
Common flags
| Flag | Accepted by | Effect |
|---|---|---|
--apply | Every command that writes | Run the printed plan, then read each write back. Without it, the command only prints the plan. |
--format text|json | Every command except watch, skills and completions | json prints one envelope: {"schema_version": 1, "command": …, "data": …}. Notices go to stderr. |
-h, --help | Every command | Print the command's help |
Every --apply takes the repository's lock. A second --apply while one runs exits 4. Exit codes are on Exit codes & environment.
Sync
carol scope
Mirror an initiative's scope.md, its tickets, contracts and edges, and its board.
| Argument or flag | Effect |
|---|---|
<SCOPE> | Path to scope.md |
--project <title> | Board title, when it isn't the scope's own title |
--apply, --format | See Common flags |
carol scope docs/billing/scope.md --apply
carol ticket
Mirror one ticket as a sub-issue of its scope issue.
| Argument or flag | Effect |
|---|---|
<TICKET> | Path to the ticket file |
--apply, --format | See Common flags |
carol ticket docs/billing/tickets/tax-rules.md --apply
carol publish
Publish a PRD as a milestone, an epic and one task issue per task.
| Argument or flag | Effect |
|---|---|
<PRD> | Path to the PRD |
--scope <n> | The scope issue's number, for a PRD outside docs/<initiative>/prds/ |
--apply, --format | See Common flags |
carol publish docs/billing/prds/prd-01-invoices.md --apply
carol board
Put a PRD's task issues on a Projects board, with each card's Status from the run.
| Argument or flag | Effect |
|---|---|
<PRD> | Path to the PRD |
--project <title> | Board title. The default is the initiative's board. |
--apply, --format | See Common flags |
carol board docs/billing/prds/prd-01-invoices.md --apply
carol sync
Mirror Zurdo's run outcome onto a PRD's task issues and its epic.
| Argument or flag | Effect |
|---|---|
<PRD> | Path to a PRD that has run state |
--apply, --format | See Common flags |
carol sync docs/billing/prds/prd-01-invoices.md --apply
carol bootstrap
Create the base labels, and describe a repository that has no description.
| Flag | Effect |
|---|---|
--about <text> | The description, set only when the repository has none and no topics |
--apply, --format | See Common flags |
carol bootstrap --about "Invoices and refunds" --apply
carol plan
Print one combined plan for several planning files, inferring each file's mode from its path.
| Argument or flag | Effect |
|---|---|
<FILES>... | scope.md plans as scope, tickets/*.md as ticket, any other .md as publish |
--format | See Common flags |
carol plan docs/billing/scope.md docs/billing/prds/prd-02-refunds.md
carol apply
Apply the combined plan for several planning files, after asking for confirmation.
| Argument or flag | Effect |
|---|---|
<FILES>... | As for carol plan |
--yes | Skip the apply N ops? [y/N] prompt |
--format | See Common flags |
carol apply --yes docs/billing/scope.md docs/billing/prds/prd-02-refunds.md
Read-only
carol doctor
Check gh, the base labels, Zurdo and the skills, plus the App when configured.
| Flag | Effect |
|---|---|
--format | json lists each check with name and ok |
carol doctor
carol status
Show an initiative's phases, run states, row conflicts and handoff freshness, offline.
| Argument or flag | Effect |
|---|---|
[INITIATIVE] | The initiative's directory name. Optional when there is only one. |
--format | json prints the full map. See Internals. |
carol status billing --format json
carol handoff check
Validate a handoff file's structure, printing one finding per line.
| Argument or flag | Effect |
|---|---|
<FILE> | Path to handoff.md |
--format | json prints the standard envelope, with findings at data.findings, each with line, message and rule |
carol handoff check docs/billing/handoff.md
carol score
Report each run task's outcome beside the authoring warnings its PRD drew.
| Flag | Effect |
|---|---|
--report | Required. Print the report, the only mode. |
--format | See Common flags |
carol score --report
carol usage
Report this repository's AI usage from each harness's local store, in tokens.
| Flag | Effect |
|---|---|
--apply | Rewrite this machine's section of the pinned AI usage issue |
--format | See Common flags |
carol usage --apply
carol triage
Label hand-filed issues by area globs and route them to people.
| Flag | Effect |
|---|---|
--apply, --format | See Common flags. Needs [triage.area_globs]. |
carol triage --apply
Engine loop
These commands write as the GitHub App and need [identity] and CAROL_APP_KEY.
carol propose
Open a proposal for each open phase without an epic, and rank them with priorities.
| Argument or flag | Effect |
|---|---|
<SCOPE> | Path to scope.md |
--apply, --format | See Common flags |
carol propose docs/billing/scope.md --apply
carol specify
Draft an accepted, ready phase's PRD with zurdo scaffold and open its pull request.
| Argument or flag | Effect |
|---|---|
<SCOPE> | Path to scope.md |
<PHASE> | The phase id, such as phase-02 |
--apply, --format | See Common flags |
carol specify docs/billing/scope.md phase-02 --apply
carol run
Run a specified phase's merged PRD with zurdo run, open the run pull request, and post Zurdo's report on it as a run-report comment.
| Argument or flag | Effect |
|---|---|
<SCOPE> | Path to scope.md |
<PHASE> | The phase id |
--apply, --format | See Common flags |
carol run docs/billing/scope.md phase-02 --apply
carol report
Sync a running phase's tasks and post the run's verdict on its epic, read from the run pull request's run-report comment, so any checkout can report.
| Argument or flag | Effect |
|---|---|
<SCOPE> | Path to scope.md |
<PHASE> | The phase id |
--apply, --format | See Common flags |
carol report docs/billing/scope.md phase-02 --apply
carol tick
Plan the one transition due for each phase, from one snapshot of the tracker, from a design session through to the release and the phase review, and the research session or question due for each open ticket. See The engine loop.
| Argument or flag | Effect |
|---|---|
<SCOPE> | Path to scope.md |
--apply, --format | See Common flags. A refused item doesn't stop the others. |
carol tick docs/billing/scope.md --apply
carol watch
Loop tick --apply in the foreground until Ctrl-C, taking the lock for each tick.
| Argument or flag | Effect |
|---|---|
<SCOPE> | Path to scope.md |
--interval <n>s|<n>m|<n>h | Time between ticks. The default is 10m. |
--apply | Required. Without it, watch exits 2. |
carol watch docs/billing/scope.md --interval 5m --apply
Skills and shell
carol skills list
Print the skills bundled in the binary, one per line.
| Flag | Effect |
|---|---|
-h, --help | Print help. It takes no other flag. |
carol skills list
carol skills install
Write the bundled skills into each provider's personal skills directory.
| Argument or flag | Effect |
|---|---|
[NAMES]... | Skills to install. All of them when none are named. |
--provider <name> | anthropic, codex or copilot. Repeatable. |
--all-providers | Install for every provider, the default |
carol skills install --provider anthropic
carol completions
Print a shell completion script to stdout.
| Argument | Effect |
|---|---|
<SHELL> | bash, zsh, fish, elvish or powershell |
eval "$(carol completions zsh)"
Next: Configuration