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.