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)[source]

Apply bold ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.cli.dim(text)[source]

Apply dim ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.cli.green(text)[source]

Apply green ANSI color to text.

Parameters:

text (str)

Return type:

str

plan_view.cli.bold_cyan(text)[source]

Apply bold cyan ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.cli.bold_yellow(text)[source]

Apply bold yellow ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.cli.now_iso()[source]

Return current UTC time in ISO 8601 format.

Return type:

str

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

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)[source]

Save plan.json with updated timestamp and sorted phases.

Parameters:
Return type:

None

plan_view.cli.load_schema()[source]

Load the bundled JSON schema.

Return type:

dict

plan_view.cli.resolve_plan_path(explicit_path=None)[source]

Resolve the plan.json path using config files if no explicit path given.

Resolution order: 1. If explicit_path is provided and not the default, use it directly 2. Search for .pv.toml or pyproject.toml [tool.pv] walking up from cwd 3. If config found with plan_file setting, resolve relative to config location 4. Fall back to ./plan.json

Config file format (.pv.toml or pyproject.toml [tool.pv]):

plan_file = “path/to/plan.json” # Relative to config file location

Parameters:

explicit_path (Path | None)

Return type:

Path

plan_view.cli.recalculate_progress(plan)[source]

Recalculate all progress fields.

Parameters:

plan (dict)

Return type:

None

plan_view.cli.get_current_phase(plan)[source]

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)[source]

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)[source]

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

Parameters:
Return type:

tuple[dict, dict] | None

plan_view.cli.find_phase(plan, phase_id)[source]

Find a phase by ID.

Parameters:
Return type:

dict | None

plan_view.cli.task_to_dict(phase, task)[source]

Convert a task to a JSON-serializable dict.

Parameters:
Return type:

dict

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

Display full plan overview with all phases and tasks.

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

Parameters:
Return type:

None

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

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

Parameters:
Return type:

None

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

Display the next task to work on.

Parameters:
Return type:

None

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

Display current phase details with all tasks and dependencies.

Parameters:
Return type:

None

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

Display a specific task or phase by ID.

Parameters:
Return type:

None

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

Display recently completed tasks.

Parameters:
Return type:

None

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

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

Parameters:
Return type:

None

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

Display summary of plan progress.

Parameters:
Return type:

None

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

Display plan or phase tasks in table format.

Parameters:
Return type:

None

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

Display bugs phase with all tasks.

Parameters:
Return type:

None

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

Display deferred phase with all tasks.

Parameters:
Return type:

None

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

Display ideas phase with all tasks.

Parameters:
Return type:

None

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

Validate plan against JSON schema.

Parameters:
Return type:

None

plan_view.cli.cmd_ai_context(plan)[source]

Output minimal context for AI agents: next task + current phase + key info.

Parameters:

plan (dict)

Return type:

None

plan_view.cli.cmd_ai_actionable(plan)[source]

Output only actionable tasks (pending with deps met) for AI agents.

Parameters:

plan (dict)

Return type:

None

plan_view.cli.cmd_ai_files(plan, task_id=None)[source]

Output files for a task or current task.

Parameters:
Return type:

None

plan_view.cli.cmd_init(args)[source]

Create a new plan.json.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_add_phase(plan, args)[source]

Add a new phase.

Parameters:
Return type:

None

plan_view.cli.cmd_add_task(plan, args)[source]

Add a new task to a phase.

Parameters:
Return type:

None

plan_view.cli.cmd_set(plan, args)[source]

Set a task field.

Parameters:
Return type:

None

plan_view.cli.cmd_done(args)[source]

Mark task as completed.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_start(args)[source]

Mark task as in_progress.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_block(args)[source]

Mark task as blocked.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_skip(args)[source]

Mark task as skipped.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_defer(plan, args)[source]

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

Parameters:
Return type:

None

plan_view.cli.cmd_bug(plan, args)[source]

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

Parameters:
Return type:

None

plan_view.cli.cmd_idea(plan, args)[source]

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

Parameters:
Return type:

None

plan_view.cli.cmd_rm(plan, args)[source]

Remove a phase or task.

Parameters:
Return type:

None

plan_view.cli.cmd_compact(plan, args)[source]

Backup plan and compact completed tasks to minimal fields.

Parameters:
Return type:

None

plan_view.cli.cmd_restore(args)[source]

List restore points and restore a chosen backup.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_completion(args)[source]

Print shell completion script to stdout.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.cmd_complete(args)[source]

Output completion values, one per line. Hidden subcommand for shell scripts.

Parameters:

args (Namespace)

Return type:

None

plan_view.cli.main()[source]

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_ai_context(plan)[source]

Output minimal context for AI agents: next task + current phase + key info.

Parameters:

plan (dict)

Return type:

None

plan_view.commands.view.cmd_ai_actionable(plan)[source]

Output only actionable tasks (pending with deps met) for AI agents.

Parameters:

plan (dict)

Return type:

None

plan_view.commands.view.cmd_ai_files(plan, task_id=None)[source]

Output files for a task or current task.

Parameters:
Return type:

None

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

Display full plan overview with all phases and tasks.

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

Parameters:
Return type:

None

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

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

Parameters:
Return type:

None

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

Display the next task to work on.

Parameters:
Return type:

None

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

Display current phase details with all tasks and dependencies.

Parameters:
Return type:

None

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

Display a specific task or phase by ID.

Parameters:
Return type:

None

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

Display recently completed tasks.

Parameters:
Return type:

None

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

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

Parameters:
Return type:

None

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

Display summary of plan progress.

Parameters:
Return type:

None

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

Validate plan against JSON schema.

Parameters:
Return type:

None

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

Display bugs phase with all tasks.

Parameters:
Return type:

None

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

Display deferred phase with all tasks.

Parameters:
Return type:

None

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

Display ideas phase with all tasks.

Parameters:
Return type:

None

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

Display plan or phase tasks in table format.

Parameters:
Return type:

None

Edit Commands

Commands for modifying plan data.

Edit commands for modifying plan data.

plan_view.commands.edit.cmd_init(args)[source]

Create a new plan.json.

Parameters:

args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_add_phase(plan, args)[source]

Add a new phase.

Parameters:
Return type:

None

plan_view.commands.edit.cmd_add_task(plan, args)[source]

Add a new task to a phase.

Parameters:
Return type:

None

plan_view.commands.edit.cmd_set(plan, args)[source]

Set a task field.

Parameters:
Return type:

None

plan_view.commands.edit.cmd_done(args)[source]

Mark task as completed.

Parameters:

args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_start(args)[source]

Mark task as in_progress.

Parameters:

args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_block(args)[source]

Mark task as blocked.

Parameters:

args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_skip(args)[source]

Mark task as skipped.

Parameters:

args (Namespace)

Return type:

None

plan_view.commands.edit.cmd_defer(plan, args)[source]

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

Parameters:
Return type:

None

plan_view.commands.edit.cmd_bug(plan, args)[source]

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

Parameters:
Return type:

None

plan_view.commands.edit.cmd_idea(plan, args)[source]

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

Parameters:
Return type:

None

plan_view.commands.edit.cmd_rm(plan, args)[source]

Remove a phase or task.

Parameters:
Return type:

None

plan_view.commands.edit.cmd_compact(plan, args)[source]

Backup plan and compact completed tasks to minimal fields.

Parameters:
Return type:

None

plan_view.commands.edit.cmd_reconcile(plan, args)[source]

Reconcile plan data: fix inconsistencies and validate.

Parameters:
Return type:

None

plan_view.commands.edit.cmd_restore(args)[source]

List restore points and restore a chosen backup.

Parameters:

args (Namespace)

Return type:

None

I/O

Plan loading, saving, and validation.

Plan file I/O operations.

plan_view.io.resolve_plan_path(explicit_path=None)[source]

Resolve the plan.json path using config files if no explicit path given.

Resolution order: 1. If explicit_path is provided and not the default, use it directly 2. Search for .pv.toml or pyproject.toml [tool.pv] walking up from cwd 3. If config found with plan_file setting, resolve relative to config location 4. Fall back to ./plan.json

Config file format (.pv.toml or pyproject.toml [tool.pv]):

plan_file = “path/to/plan.json” # Relative to config file location

Parameters:

explicit_path (Path | None)

Return type:

Path

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

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)[source]

Save plan.json with updated timestamp and sorted phases.

Parameters:
Return type:

None

plan_view.io.maybe_periodic_backup(path, plan)[source]

Create periodic delta backups every 15 saves. Never raises.

Parameters:
Return type:

None

plan_view.io.load_schema()[source]

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)[source]

Recalculate all progress fields.

Parameters:

plan (dict)

Return type:

None

plan_view.state.get_current_phase(plan)[source]

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)[source]

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)[source]

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

Parameters:
Return type:

tuple[dict, dict] | None

plan_view.state.find_phase(plan, phase_id)[source]

Find a phase by ID.

Parameters:
Return type:

dict | None

plan_view.state.task_to_dict(phase, task)[source]

Convert a task to a JSON-serializable dict.

Parameters:
Return type:

dict

plan_view.state.get_all_task_ids(plan, limit=5)[source]

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

Parameters:
Return type:

list[tuple[str, str, str]]

plan_view.state.get_all_phase_ids(plan)[source]

Get phase IDs with names.

Parameters:

plan (dict)

Return type:

list[tuple[str, str]]

plan_view.state.format_task_suggestions(plan, limit=5)[source]

Format task suggestions for error messages.

Parameters:
Return type:

str

plan_view.state.format_phase_suggestions(plan)[source]

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)[source]

Apply bold ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.formatting.dim(text)[source]

Apply dim ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.formatting.green(text)[source]

Apply green ANSI color to text.

Parameters:

text (str)

Return type:

str

plan_view.formatting.bold_cyan(text)[source]

Apply bold cyan ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.formatting.bold_yellow(text)[source]

Apply bold yellow ANSI formatting to text.

Parameters:

text (str)

Return type:

str

plan_view.formatting.now_iso()[source]

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)[source]

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)
    ...