3.0.0-beta.15). Features may change before the next stable release.Switch to stable →ak plan
ak plan parse
Read a plan directory into a structured summary without opening or changing the local plan store.
Use ak plan parse to read plan.md and its phase-NN-*.md files directly
from one directory and calculate phase/task progress.
Usage
ak plan parse <path>The command requires exactly one directory path and has no command-specific flags.
Read a human or JSON summary
ak plan parse ./plans/260802-1030-release-docs
ak plan parse ./plans/260802-1030-release-docs --jsonThe parser reads title, description, status, and priority from simple
plan.md front matter. It scans direct child files whose names match
phase-NN-<slug>.md, orders them by number, and reports checkbox totals and
completion percentages.
When a phase has checkboxes, they determine its status. A phase without checkboxes uses recognized front-matter status. Unknown plan fields are ignored.
Parsing is intentionally a structured read, not a full format validation.
A directory with a readable plan.md can parse even when metadata is
incomplete. Use ak plan validate <path> when validity must gate a workflow.
Effects and privacy
The command is read-only: it does not open or initialize the plan store, write files, prompt, read stdin, contact the network, authenticate, or invoke a provider.
Human output is written to stdout. JSON success is one envelope with
kind=plan.parse; data includes plan metadata, total/done counts,
percentages, and a phases array. The dir and each phase's file_path are
absolute paths, while titles and descriptions can contain private project
context. Redact before sharing.
There is no NDJSON mode. JSON execution errors use the structured envelope on
stderr. With --json enabled, unknown or invalid flags use the shared JSON stderr
error envelope (error_code: validation_failed, exit 2). Human mode, including
--json=false, prints Usage.
Exit behavior
| Exit | Meaning | Safe next step |
|---|---|---|
0 | The directory was parsed and summarized. A plan with zero tasks is valid output with 0%. | Inspect the returned fields or run validation separately. |
1 | plan.md was missing/unreadable, the directory could not be scanned, or a matching phase could not be parsed. | Fix the named file or directory before retrying. |
2 | The argument count or flags were invalid. | Supply exactly one plan-directory path. |