Quick Start

Project Planner accepts YAML and Python plan files. The repository includes examples under planner/examples.

Pip installations include this guide for offline use. Open it with planner docs, or print its index.html location with planner docs --path. Neither command needs a plan, configuration file or internet connection.

Run these commands from the repository root:

planner validate planner/examples/tasks.yaml
planner list tasks planner/examples/tasks.yaml
planner list deliverables planner/examples/tasks.yaml
planner list activities planner/examples/tasks.yaml
planner list workitems planner/examples/tasks.yaml
planner list risks planner/examples/tasks.yaml
planner list plan planner/examples/tasks.yaml
planner list planner/examples/tasks.yaml label
planner list planner/examples/tasks.yaml status assignees
planner list-detail planner/examples/tasks.yaml
planner summary planner/examples/tasks.yaml
planner schedule planner/examples/tasks.yaml
planner composite planner/examples/tasks.yaml /tmp/expanded.yaml
# Planner initializes the default user configuration automatically on first use.
planner export planner/examples/tasks.yaml /tmp/plan.docx
planner export planner/examples/tasks.yaml /tmp/plan.svg
planner export planner/examples/tasks.yaml /tmp/plan.pptx
planner export-gantt planner/examples/tasks.yaml /tmp/gantt.svg
planner export-gantt planner/examples/tasks.yaml /tmp/gantt.pptx

To export the same document layout as PDF on macOS or Windows with Microsoft Word installed, use planner export planner/examples/tasks.yaml /tmp/plan.pdf. Allow automation of Word if prompted.

Import a Word Plan

To start from a document structured like a planner Word export:

planner import proposal.docx
planner validate proposal.yaml

Output defaults to proposal.yaml beside the source; an optional second filename overrides it. The output must be a new file. Relative paths use the current directory; planner environment overrides do not apply. Use --config PATH to identify custom table headers when needed.

Import creates a draft with label-based task IDs and review comments. Recovered explicit IDs are preserved; generated ID collisions receive numeric suffixes. Missing forecast start/end dates can be inferred using full-year bounds from positive annual funding, preserving recovered timing and unfunded status where possible. Missing status or unrecoverable required timing becomes a planning placeholder. Review inferred dates and funding gaps before using the plan. YAML uses execution and resourcing containers; comment dividers separate top-level fields, and blank lines separate entries with IDs. See Command Line Interface for recoverable fields and limitations.

Start with a Placeholder

While developing a plan, a task needs only five task fields with status: planning:

execution:
  tasks:
    - id: FUTURE_DESIGN
      category: development
      priority: capability
      label: Future design work
      description: Scope and deliverables to be developed.
      status: planning

Save this as draft.yaml and run planner validate draft.yaml or planner list draft.yaml. Add estimates and risks as they become known. Timing remains unscheduled until both start and expected are supplied; funding estimates contribute to totals without creating dates. See Plan Schema.

Default Plan File

Set TUXFAN_PLANNER_DATA_FILE to omit the input file for most commands:

An empty value behaves as unset; supply an explicit input filename in that case.

export TUXFAN_PLANNER_DATA_FILE=planner/examples/tasks.yaml
# Planner initializes the default user configuration automatically on first use.
planner validate
planner list tasks
planner list deliverables
planner list label
planner composite /tmp/expanded.yaml
planner list-detail
planner export /tmp/plan.docx
planner export /tmp/plan.svg
planner export-gantt /tmp/gantt.pptx

Use list KIND FIELD for scoped fields (for example, list deliverables status). Run planner list KIND --help for each kind’s choices. The legacy list [task_file] FIELD syntax remains available to specialize output by any supported field identifier, such as label, status, assignees, or mitigation. Combine field names to display several fields. Nested selections retain activity, task, and item context; container names such as workitems show complete contents. Combine field selection with --only tags=gpu to filter tasks first. label alone gives a compact label outline. The former --labels flag is rejected. Run planner list --help for supported field names. See Command Line Interface for filtering and Composite YAML Plans for splitting YAML inputs across files. validate reports PASS/FAIL and statistics, with warning details after the warning count.

Working with a Data Directory

To select among multiple plan files without typing their directory each time:

export TUXFAN_PLANNER_DATA_DIRECTORY="$PWD/data"
# Planner initializes the default user configuration automatically on first use.
planner validate tasks.yaml
planner list composite.yaml label
planner export tasks.yaml /tmp/airplane.docx

Relative input names use that directory in preference to the current directory. If the file is missing there, the same relative filename is tried in the current directory. Absolute input paths bypass it. Output paths, export-options paths, and relative include paths keep their existing meanings. Set TUXFAN_PLANNER_DATA_FILE as well to choose a default filename. See Development Data for the canonical fictional fixture used for development.

Shell Completion

The CLI prints completion scripts for bash, zsh, and fish:

planner completion bash
planner completion zsh
planner completion fish

For a one-session bash setup:

source <(planner completion bash)

Full Terminal Plans

planner list tasks.yaml displays the entire planning document in the terminal. Export selection, columns, and note settings do not limit it. planner list tasks tasks.yaml keeps the compact task-only view, while planner list tasks.yaml summary tasks uses existing field projections. Normal color, wrapping, filtering, and paging controls apply.

Find Command Help

Use planner help for the command overview, planner help fields for mapping templates, or planner list help tasks for scoped task-list help. These are aliases for the corresponding --help forms and use the same colors and pager without loading a plan or initializing configuration.