ak plan list

List the current project's plans from files first, best-effort-overlay index-owned fields, and understand cross-project scope limits.

Use ak plan list to inspect the current project's plans. The command reads canonical files under the project's plans/ directory first, then best-effort-overlays index-owned fields (state, issue_number, linked_pr, current_phase) from the local plan store when it opens. By default it scopes results to the current project and excludes closed and archived plans.

Usage

ak plan list

Command flags

Flag	Default	Description
`--all`	`false`	List plans across every tracked project. Requires the local plan store, since files are single-project by design.
`--include-closed`	`false`	Include lifecycle state `closed`.
`--include-archived`	`false`	Include lifecycle state `archived`.

Common examples

ak plan list
ak plan list --all
ak plan list --all --include-closed --include-archived --json

Current-project matching uses Git/repository context, including the normalized remote URL or project path. An empty result is successful and is represented by an empty JSON array.

Understand the files-first model

The rows come from canonical plan files under the current repository's ./plans/. Opening the store best-effort attaches index-owned fields to each row and can create the private directory/database or apply forward-only schema migrations. When the store is unwritable, corrupt, or its schema is newer than the running CLI, the overlay is skipped, index-only fields are absent, and stderr carries a warning; the file-derived rows still render.

Cross-project scope needs the store because files are single-project by design. Without the store, --all returns only the current project's files and warns that cross-project scope requires the index.

The command does not change plan lifecycle state or repository files, but store initialization and schema migration are possible local disk effects. Current-project resolution can run local git commands. No network, authentication, provider, or remote cache is involved.

Output and privacy

Pretty output prints one row per plan; plain output is tab-separated. JSON success uses kind=plan.list, with data as an array of summaries containing:

id, project_slug, repo_url, project_path, branch, worktree,
task_title, backend, status, state, issue_number, linked_pr, updated_at

The repository URL, branch, title, and absolute paths can reveal private local context. Redact before sharing. Success is on stdout; fallback warnings and errors use stderr. There is no NDJSON mode.

Exit behavior

Exit	Meaning	Safe next step
`0`	The current project's plan files were listed, with or without the index overlay, including an empty result.	Check stderr for a degraded-scope warning.
`1`	Plan file scanning, project-context resolution, or an unrecoverable store error failed the command.	Follow the index permission/upgrade hint; do not delete canonical plan files.
`2`	Arguments or flags were invalid.	Remove positional arguments and correct flags.