API Reference

Complete API documentation for plan-view, generated from source code docstrings.

---

CLI Entry Point

The main CLI module that dispatches to view and edit commands.

CLI for viewing and editing plan.json files.

plan_view.cli.bold(text)

Apply bold ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.cli.dim(text)

Apply dim ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.cli.green(text)

Apply green ANSI color to text.

Parameters:

text (str)

Return type:

str

plan_view.cli.bold_cyan(text)

Apply bold cyan ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.cli.bold_yellow(text)

Apply bold yellow ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.cli.now_iso()

Return current UTC time in ISO 8601 format.

Return type:

str

plan_view.cli.load_plan(path, *, auto_migrate=False)

Load and parse plan.json, ensuring special phases exist.

Parameters:

• path (Path) – Path to the plan.json file.

• auto_migrate (bool) – If True, save the plan after adding missing special phases.

Return type:

dict | None

plan_view.cli.save_plan(path, plan)

Save plan.json with updated timestamp and sorted phases.

Parameters:

• path (Path)

• plan (dict)

Return type:

None

plan_view.cli.load_schema()

Load the bundled JSON schema.

Return type:

dict

plan_view.cli.recalculate_progress(plan)

Recalculate all progress fields.

Parameters:

plan (dict)

Return type:

None

plan_view.cli.get_current_phase(plan)

Find the current in_progress or first pending phase (skips special phases).

Parameters:

plan (dict)

Return type:

dict | None

plan_view.cli.get_next_task(plan)

Find the next actionable task with all dependencies met (skips special phases).

Parameters:

plan (dict)

Return type:

tuple[dict, dict] | None

plan_view.cli.find_task(plan, task_id)

Find a task by ID (exact or prefix match), return (phase, task) or None.

Parameters:

• plan (dict)

• task_id (str)

Return type:

tuple[dict, dict] | None

plan_view.cli.find_phase(plan, phase_id)

Find a phase by ID.

Parameters:

• plan (dict)

• phase_id (str)

Return type:

dict | None

plan_view.cli.task_to_dict(phase, task)

Convert a task to a JSON-serializable dict.

Parameters:

• phase (dict)

• task (dict)

Return type:

dict

plan_view.cli.cmd_overview(plan, *, as_json=False, show_all=False)

Display full plan overview with all phases and tasks.

By default, completed phases are hidden. Use –all to show everything.

Parameters:

• plan (dict)

• as_json (bool)

• show_all (bool)

Return type:

None

plan_view.cli.cmd_current(plan, *, as_json=False)

Display completed phases summary, current phase, and next task.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_next(plan, *, as_json=False)

Display the next task to work on.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_phase(plan, *, as_json=False)

Display current phase details with all tasks and dependencies.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_get(plan, task_id, *, as_json=False)

Display a specific task or phase by ID.

Parameters:

• plan (dict)

• task_id (str)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_last(plan, count=5, *, as_json=False)

Display recently completed tasks.

Parameters:

• plan (dict)

• count (int | None)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_future(plan, count=5, *, as_json=False)

Display upcoming tasks (pending/in_progress), actionable first.

Parameters:

• plan (dict)

• count (int | None)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_summary(plan, *, as_json=False)

Display summary of plan progress.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_table(plan, phase_id=None, *, as_json=False)

Display plan or phase tasks in table format.

Parameters:

• plan (dict)

• phase_id (str | None)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_bugs(plan, *, as_json=False)

Display bugs phase with all tasks.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_deferred(plan, *, as_json=False)

Display deferred phase with all tasks.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_ideas(plan, *, as_json=False)

Display ideas phase with all tasks.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_validate(plan, path, *, as_json=False)

Validate plan against JSON schema.

Parameters:

• plan (dict)

• path (Path)

• as_json (bool)

Return type:

None

plan_view.cli.cmd_init(args)

Create a new plan.json.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_add_phase(plan, args)

Add a new phase.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.cli.cmd_add_task(plan, args)

Add a new task to a phase.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.cli.cmd_set(plan, args)

Set a task field.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.cli.cmd_done(args)

Mark task as completed.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_start(args)

Mark task as in_progress.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_block(args)

Mark task as blocked.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_skip(args)

Mark task as skipped.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_defer(plan, args)

Move task to deferred phase, or create a new deferred task if input is not an existing task ID.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.cli.cmd_bug(plan, args)

Move task to bugs phase, or create a new bug if input is not an existing task ID.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.cli.cmd_idea(plan, args)

Move task to ideas phase, or create a new idea if input is not an existing task ID.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.cli.cmd_rm(plan, args)

Remove a phase or task.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.cli.cmd_compact(plan, args)

Backup plan and compact completed tasks to minimal fields.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.cli.main()

CLI entry point for pv command.

Return type:

None

---

View Commands

Commands for reading and displaying plan data.

View commands for displaying plan information.

plan_view.commands.view.cmd_overview(plan, *, as_json=False, show_all=False)

Display full plan overview with all phases and tasks.

By default, completed phases are hidden. Use –all to show everything.

Parameters:

• plan (dict)

• as_json (bool)

• show_all (bool)

Return type:

None

plan_view.commands.view.cmd_current(plan, *, as_json=False)

Display completed phases summary, current phase, and next task.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.commands.view.cmd_next(plan, *, as_json=False)

Display the next task to work on.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.commands.view.cmd_phase(plan, *, as_json=False)

Display current phase details with all tasks and dependencies.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.commands.view.cmd_get(plan, task_id, *, as_json=False)

Display a specific task or phase by ID.

Parameters:

• plan (dict)

• task_id (str)

• as_json (bool)

Return type:

None

plan_view.commands.view.cmd_last(plan, count=5, *, as_json=False)

Display recently completed tasks.

Parameters:

• plan (dict)

• count (int | None)

• as_json (bool)

Return type:

None

plan_view.commands.view.cmd_future(plan, count=5, *, as_json=False)

Display upcoming tasks (pending/in_progress), actionable first.

Parameters:

• plan (dict)

• count (int | None)

• as_json (bool)

Return type:

None

plan_view.commands.view.cmd_summary(plan, *, as_json=False)

Display summary of plan progress.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.commands.view.cmd_validate(plan, path, *, as_json=False)

Validate plan against JSON schema.

Parameters:

• plan (dict)

• path (Path)

• as_json (bool)

Return type:

None

plan_view.commands.view.cmd_bugs(plan, *, as_json=False)

Display bugs phase with all tasks.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.commands.view.cmd_deferred(plan, *, as_json=False)

Display deferred phase with all tasks.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.commands.view.cmd_ideas(plan, *, as_json=False)

Display ideas phase with all tasks.

Parameters:

• plan (dict)

• as_json (bool)

Return type:

None

plan_view.commands.view.cmd_table(plan, phase_id=None, *, as_json=False)

Display plan or phase tasks in table format.

Parameters:

• plan (dict)

• phase_id (str | None)

• as_json (bool)

Return type:

None

---

Edit Commands

Commands for modifying plan data.

Edit commands for modifying plan data.

plan_view.commands.edit.cmd_init(args)

Create a new plan.json.

Parameters:

args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_add_phase(plan, args)

Add a new phase.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_add_task(plan, args)

Add a new task to a phase.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_set(plan, args)

Set a task field.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_done(args)

Mark task as completed.

Parameters:

args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_start(args)

Mark task as in_progress.

Parameters:

args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_block(args)

Mark task as blocked.

Parameters:

args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_skip(args)

Mark task as skipped.

Parameters:

args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_defer(plan, args)

Move task to deferred phase, or create a new deferred task if input is not an existing task ID.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_bug(plan, args)

Move task to bugs phase, or create a new bug if input is not an existing task ID.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_idea(plan, args)

Move task to ideas phase, or create a new idea if input is not an existing task ID.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_rm(plan, args)

Remove a phase or task.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_compact(plan, args)

Backup plan and compact completed tasks to minimal fields.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_reconcile(plan, args)

Reconcile plan data: fix inconsistencies and validate.

Parameters:

• plan (dict)

• args (Namespace)

Return type:

None

---

I/O

Plan loading, saving, and validation.

Plan file I/O operations.

plan_view.io.load_plan(path, *, auto_migrate=False)

Load and parse plan.json, ensuring special phases exist.

Parameters:

• path (Path) – Path to the plan.json file.

• auto_migrate (bool) – If True, save the plan after adding missing special phases.

Return type:

dict | None

plan_view.io.save_plan(path, plan)

Save plan.json with updated timestamp and sorted phases.

Parameters:

• path (Path)

• plan (dict)

Return type:

None

plan_view.io.load_schema()

Load the bundled JSON schema.

Return type:

dict

---

State

Plan state management and task lookup.

Plan state calculations and lookup operations.

plan_view.state.recalculate_progress(plan)

Recalculate all progress fields.

Parameters:

plan (dict)

Return type:

None

plan_view.state.get_current_phase(plan)

Find the current in_progress or first pending phase (skips special phases).

Parameters:

plan (dict)

Return type:

dict | None

plan_view.state.get_next_task(plan)

Find the next actionable task with all dependencies met (skips special phases).

Parameters:

plan (dict)

Return type:

tuple[dict, dict] | None

plan_view.state.find_task(plan, task_id)

Find a task by ID (exact or prefix match), return (phase, task) or None.

Parameters:

• plan (dict)

• task_id (str)

Return type:

tuple[dict, dict] | None

plan_view.state.find_phase(plan, phase_id)

Find a phase by ID.

Parameters:

• plan (dict)

• phase_id (str)

Return type:

dict | None

plan_view.state.task_to_dict(phase, task)

Convert a task to a JSON-serializable dict.

Parameters:

• phase (dict)

• task (dict)

Return type:

dict

plan_view.state.get_all_task_ids(plan, limit=5)

Get task IDs with titles and phase names (limited for display).

Parameters:

• plan (dict)

• limit (int)

Return type:

list[tuple[str, str, str]]

plan_view.state.get_all_phase_ids(plan)

Get phase IDs with names.

Parameters:

plan (dict)

Return type:

list[tuple[str, str]]

plan_view.state.format_task_suggestions(plan, limit=5)

Format task suggestions for error messages.

Parameters:

• plan (dict)

• limit (int)

Return type:

str

plan_view.state.format_phase_suggestions(plan)

Format phase suggestions for error messages.

Parameters:

plan (dict)

Return type:

str

---

Formatting

Terminal output formatting and styling.

ANSI terminal formatting utilities for pv-tool.

plan_view.formatting.bold(text)

Apply bold ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.formatting.dim(text)

Apply dim ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.formatting.green(text)

Apply green ANSI color to text.

Parameters:

text (str)

Return type:

str

plan_view.formatting.bold_cyan(text)

Apply bold cyan ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.formatting.bold_yellow(text)

Apply bold yellow ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.formatting.now_iso()

Return current UTC time in ISO 8601 format.

Return type:

str

---

Decorators

CLI decorator utilities.

Decorators for command functions.

plan_view.decorators.require_plan(func)

Decorator to load plan from args.file and inject it as first argument.

This eliminates the boilerplate of loading plan, checking for None, and asserting for the type checker. The wrapped function receives the loaded plan dict as its first positional argument.

Parameters:

func (Callable[[Concatenate[dict, Namespace, ParamSpec(P)]], TypeVar(R)]) – Command function that takes (plan: dict, args: Namespace, …) -> R

Returns:

Namespace, …) -> R

Return type:

Wrapped function that takes (args

Example:

@require_plan
def cmd_add_task(plan: dict, args: argparse.Namespace) -> None:
    phase = find_phase(plan, args.phase)
    ...