Command Line Interface

The package installs two console scripts:

planner

Primary command.

tuxfan-planner

Backward-compatible alias.

Run planner --version or planner -v to print only the current version number and exit successfully, without loading a plan or configuration. Both console scripts support these options.

Help Topics

Each command and scoped list view starts with a one-line purpose statement below usage, before its arguments and options. Help then uses short Examples, Notes, and Related sections, followed by a reference to the relevant manual. The examples use fictional files and can be copied as command patterns. Notes keep the essential defaults, conflicts, write restrictions and recovery requirements close to the command. Exhaustive schema rules, rendering details and migration guidance belong in this reference and the configuration/export manuals. Run avail FIELD for a field’s actual choices.

For example, planner export --help shows DOCX, PowerPoint and PDF examples, then explains the output suffix, Word requirement for PDF, template selection and standard override. Table layout, numbering, typography, spacing and section selection are documented in Export Options and General Configuration.

Scoped list help retains field choices, concise filter syntax, relation targets and examples. show help demonstrates qualified names instead of printing every field alias; use the object-view help and field templates to explore fields, and the command reference below for the full behavior. All accepted field names and aliases retain their existing parsing.

planner help displays top-level help. Command and topic aliases invoke the same parser help as --help, with the same exit status, formatting, colors, environment information, and automatic paging:

Help aliases

Invocation

Equivalent

planner help fields or planner fields help

planner fields --help

planner help list tasks

planner list tasks --help

planner list help tasks or planner list tasks help

planner list tasks --help

planner help fields task or planner fields help task

planner fields task --help (fields command help)

planner config init help

planner config init --help (config command help)

Place help once along a valid command/topic path. Real subcommands, such as list kinds, have scoped help. Positional choices such as fields task, config init, and completion bash are validated but show their parent command’s help. Invalid topics exit with status 2 and show the nearest relevant help on stderr. Valid help exits with status 0 on stdout without reading plans, loading configuration, or initializing configuration files. Shared options such as --config PATH retain their normal parsing and conflict rules.

Option values equal to help remain ordinary values. -- ends alias recognition; for example, planner list -- help passes a filename. A filename can also be written ./help. Aliases do not apply after filenames or other unrestricted positional arguments. Help topic paths must precede --. Bash, zsh, and fish suggest command/topic names in help requests instead of input files, and offer help at command/topic boundaries.

Help and usage messages wrap at the configured width (80 characters by default), including environment variable values and filtering examples. Wrapped command descriptions align beneath the first word of their description, including when the final wrapping at the configured width (80 by default) pass needs to wrap a command row. Widths and indentation count visible text, excluding ANSI color codes from argparse and planner styling. Top-level help lists commonly used command flags as aligned option/description entries under Command options (after COMMAND), with continuation lines aligned beneath each description. Each description identifies the command that accepts the flag; these are command options, not global options. FIELD is a placeholder for exact supported list fields, such as label or status. Run planner COMMAND --help for the complete command options. On compatible terminals, this section uses a bold cyan heading, cyan option names and arguments, and green command scopes. Descriptions remain plain. Color is applied after wrapping to preserve alignment and the configured width limit. Redirected output, NO_COLOR, and TERM=dumb disable these colors.

Help and usage messages begin with tuxfan-planner on its own line, followed by the current version on a line labeled Version:. The project name is bold on compatible terminals, honoring NO_COLOR and TERM=dumb; the version line remains regular weight. In a source checkout, this follows pyproject.toml immediately after a version bump; installed packages report their distribution version. CLI errors appear red and UserWarning messages appear amber on compatible stderr terminals; redirected output, NO_COLOR, and TERM=dumb disable error color.

Input diagnostics include filename:line when a source location is known. Funding warnings point to the input funding entry, including inherited parent funding. Task and milestone validation errors identify their defining block; YAML/Python syntax errors identify the parser’s problem line. Export-options validation errors also include source locations. Line numbers are one-based. Literal Python task definitions can be located; dynamically computed task entries may report only a filename. Missing files and command-line argument errors do not invent an input line number.

Parent-only plan exports

Set export.layout.multipart: parents in the general configuration (or a per-standard override) to show one parent task entry per multipart group while retaining standalone tasks. expanded is the default. This affects task narratives/tables in Word/PDF, SVG cards and PowerPoint slides. Parent prose is retained, child prose is omitted, mixed fields display Mixed and incomplete timing is marked partial. Funding and readiness use the original parts. Parents spanning activities are placed in the first part’s activity with a warning; subtotals retain the original assignments. Gantt charts and terminal lists are unchanged. See Export Options for aggregation and import limits.

Paging long output

Set TUXFAN_PLANNER_PAGER to a pager command, for example:

export TUXFAN_PLANNER_PAGER='less -R'
planner list

Planner pages output only when both stdin and stdout are terminals, TERM is not dumb, and the displayed output exceeds the terminal height with one row reserved for the prompt. Wrapped lines count toward the height; ANSI color sequences do not. Terminal width, tabs, combining marks, and wide characters are accounted for. Short output stays direct.

Automatic color detection uses the original terminal before starting the pager, so list retains colors without --color always. less -R preserves these ANSI colors. NO_COLOR and --color never still work; disabling color does not disable paging. Redirected or piped stdout bypasses paging and retains existing color behavior.

Paging applies to list, list-detail, summary, schedule, show, avail, fields, and help printed to stdout. Stderr diagnostics, validation results, completion scripts, editing prompts, export messages, and merge/split reports remain direct. Unset, empty, or whitespace-only pager settings disable paging. Quoted executable paths and arguments are supported; shell pipelines, redirection, and shell expansion are not interpreted. If the command is malformed or cannot start, output is printed directly. Quitting the pager early is normal. Pager startup/exit does not change the planner command’s success status.

Commands

Prefix each command below with planner (or tuxfan-planner). An explicit input path overrides TUXFAN_PLANNER_DATAFILE. For export, export-gantt, and composite, the output path is always required; input may be omitted only when that environment variable is set.

When TUXFAN_PLANNER_DATA_DIRECTORY is set, relative input filenames resolve there first, then in the current directory if missing. This also applies to a relative default filename from TUXFAN_PLANNER_DATAFILE. Absolute inputs bypass the directory. Output paths and export-options paths are unaffected; included YAML paths still resolve relative to their containing files.

Read commands accept composite YAML plans, expanding !include directives before plan validation. format formats the main file and recursively included YAML sources in place. spell-check reviews prose across the main file and included YAML sources in one session, preserving include directives.

Field selectors are positional names, consistently across list, show, avail, and fields; the former --FIELD selectors are rejected. Use planner list tasks.yaml label status, planner show tasks.yaml tags, planner avail status, or planner fields task. With a default input in TUXFAN_PLANNER_DATAFILE, use planner list label status and planner show tags. List accepts multiple names and permits options before, between, or after them. Filtering and rendering controls such as --only and --color remain options.

validate [task_file] [--config PATH] [--standard VERSION]

Use --standard legacy|asc-v4|asc-v6 to override export.standard and resolve the matching configured export rules for validation. Without it, the configured standard applies. All configuration blocks remain validated, including inactive ones. This does not generate an export or modify the configuration file. For example:

planner validate plan.yaml --config configs/asc.yaml --standard asc-v4

Validate a YAML or Python plan file. Task priority and risk are optional for every status. Omitted priority is unassigned; omit risk or use risk: [] for no risks. Supplied values retain validation. Successful output is limited to Validation: PASS and counts of activities, expanded tasks, milestone definitions, activities, configured fiscal years, work item references, project dependency definitions, project and inline task risks, and emitted warnings. Activities use the same grouping as list and exports; unused activities count only under Activities. Work item references count per task, including inherited references on multipart parts. Warnings follow the active warning filters and appear on stderr with their original source locations and terminal styling, after the Warnings: N statistics line. Output is flushed before warning details so redirected streams preserve that order when combined. Warnings collected before a validation failure are also shown beneath a warning-count line. Plan metadata and narratives are omitted. Failure prints Validation: FAIL and an error diagnostic to stderr, with exit status 1; success exits with status 0. PASS is green and FAIL is red on compatible stdout terminals; redirected output, NO_COLOR, and TERM=dumb keep the status plain.

show [task_file] FIELD

Print unique non-empty values used by exactly one scalar or scalar-list field, one per line, sorted alphabetically ignoring case, with spelling and case preserved. Exact duplicates are removed; case variants remain distinct. Empty results produce no output. Normal input environment variables, validation, includes, and multipart inheritance apply. Examples: planner show tasks.yaml tags or planner show tasks.yaml assignees.

Unqualified names collect all applicable contexts, matching the canonical field names used by list. Qualified names restrict the context: tasks.status, workitems.status, risk.type, milestones.id, execution.activities.label, execution.description, and plan.project. Scalar lists are flattened, including tags, dependencies, task milestone references, assignees, and deliverables. Structured containers (tasks, risk, workitems, funding, execution) are not selectable. milestones selects task milestone references; definition fields use qualified names or shared leaf names. Exactly one field is required; abbreviations are rejected.

Names follow plan YAML keys, so a task’s activity is activity. These aliases give identical output:

  • activities for activity (the collection name used by list and --only)

  • activities.id, activities.label and activities.description for execution.activities.*

  • tasks.risk.type, tasks.risk.level, tasks.risk.description and tasks.risk.mitigation for risk.*

risk.* (and tasks.risk.*) selects inline task risks; risks.* selects project risk definitions.

fields TYPE

planner fields colors prints every effective terminal color as a plain YAML terminal.colors mapping, honoring --config. Paste this fragment into the general configuration; it does not load a plan. ANSI defaults use conventional hex equivalents. See General Configuration.

Print a copyable YAML mapping template without reading a data file. Supported types are config, colors, plan, task, workitem, risk, project-risk, dependency, milestone, deliverable, execution, and activity. Plural aliases tasks, workitems, project-risks, risks, dependencies, milestones, deliverables, and activities are accepted, along with execution.activities. risk is a private task risk; risks is a project risk definition. Types are exact; missing or unknown types are usage errors (exit status 2).

Output contains only YAML and YAML comments, without terminal styling or prose banners. Keys follow canonical input field order; nested mappings are expanded. Fixed-choice fields list all valid choices in inline comments, with severity order for risk levels, and open/closed order for work item statuses. Free-form fields use example text or empty values. Examples are starter values, not schema defaults. Optional completed periods, alternative fiscal-year lists, and multipart syntax are commented out to keep the active example valid.

planner fields task prints one task mapping. Place it under tasks as a list item with appropriate indentation. Other mapping fragments also need their containing key or list. planner fields plan > new-plan.yaml writes a complete starter plan; replace example values before use. planner fields config > new-config.yaml writes a complete configuration template from packaged defaults, including commented optional allowlists and export alternatives. It does not read or initialize the user configuration; --config is ignored for this template, even if it names an invalid or missing file. Other types use the active configuration for vocabulary examples. Task site and bnr examples honor configured allowlists. type accepts one built-in ID or a list: labor, contract, equipment, services, nonlabor. Omitted site/bnr allowlists leave those IDs unrestricted. Input environment variables and export options do not affect this command.

avail FIELD

Print finite schema options, one per line, without loading a plan or consulting input environment variables. Exactly one field is required. status prints separate labeled groups explaining task statuses (including blocked and unfunded) and work item entry statuses. Task statuses are alphabetical with closed last; work item statuses are ordered open, closed. priority lists configured task priority IDs in declaration order. level lists risk levels in severity order: low, medium, high, extreme. risk.type lists required risk types: technical, schedule, operational, external, performance. priority and category list configured IDs, labels, and descriptions. type lists the built-in task types: labor, contract, equipment, services, nonlabor. site and bnr list configured task IDs; an empty allowlist prints nothing, and an omitted allowlist produces an operational error. These fields, status, priority, level, risk.type, deliverables.type, and deliverables.status are offered in help and completions. The qualified deliverable type field lists paper, document, presentation, release, software, dataset, model, service, training, demonstration, assessment, design, hardware. The qualified deliverable status field lists required, planning, blocked, submitted, complete, closed. On compatible terminals, reusable IDs and built-in choices use bold magenta; explicit table_entry values use cyan. Labels, descriptions and headings remain plain. Redirected output, NO_COLOR and TERM=dumb disable automatic color. Paging preserves these colors. Colored and plain output use the same layout and ordering. Output wraps at the configured width (80 visible columns by default), excluding ANSI styling and accounting for wide characters and combining accents. Priority/category IDs appear on their own lines, followed by indented Label, Description, and optional table_entry fields. Field continuations align beneath their values and blank lines separate records. Other fields keep one choice per line, wrapping unusually long values when needed. planner avail colors lists terminal palette attributes, default/effective values, and colored hex values. --color auto|always|never controls all avail colors. Configure overrides through terminal.colors; see General Configuration. Standard ANSI default hex values are conventional equivalents because terminal themes can change their actual appearance. Use planner show FILE FIELD for values actually used in a plan. Unsupported fields, unknown fields, containers, missing fields, and multiple fields are usage errors (exit status 2). Use --help to see all selectable field names.

merge task_file TASK_ID TASK_ID... --id PARENT_ID --label LABEL --output output.yaml

Merge at least two standalone tasks defined in this YAML file into one multipart task. Accept a raw task-list fragment or a mapping containing tasks; a complete plan is not required. The parent replaces the earliest selected task, and parts follow source declaration order, regardless of identifier order on the command line. Identical shared fields may move to the parent; differing values and funding remain on parts. The parent ID must be new. Expanded part IDs generally gain its prefix. Dependencies between merged parts retain short sibling IDs; references from other tasks are rewritten to expanded IDs. The loader resolves both forms to the same expanded task identifiers in their respective scopes.

split task_file PARENT_ID --output output.yaml [funding {parts,equal}]

Replace a locally defined multipart parent with standalone tasks in part declaration order. Materialize inherited parent fields, honoring explicit part overrides and clears. Retain expanded IDs, resolve sibling references, and replace dependencies on the removed parent with all resulting IDs.

A parent funding field requires an explicit policy. --funding parts preserves effective part funding; inherited parent amounts can multiply totals. --funding equal replaces part funding with equal shares of the parent budget, preserving whole cents and assigning remainder cents to earlier parts. It requires a parent budget with whole-cent numeric amounts; unsuffixed amounts follow the planner convention of thousands of dollars.

Both commands require explicit input and output paths, use exact identifiers, and never change the source or overwrite existing output files. Relative inputs respect TUXFAN_PLANNER_DATA_DIRECTORY; outputs remain relative to the current directory. TUXFAN_PLANNER_DATAFILE does not supply these commands’ input. They preserve YAML comments and scalar styles where possible, BOMs, and newline conventions, though indentation may normalize. Values already written as > or | blocks keep their style; other long prose becomes a > block and multi-line text a | block. Python is not supported.

The report includes ID mappings, local dependency rewrite counts, funding policies and local before/after totals where available. References are rewritten only inside the supplied document. Includes remain external and their relative paths are rebased to preserve their targets when the output directory changes. Tasks must be selected in their defining file, not through an include.

Fragment checks validate supplied fields, duplicate visible IDs and visible dependency cycles. Unresolved external dependencies, milestone and execution references, missing required fields and fields supplied through includes require the containing plan. Tasks containing include directives are left for contextual validation. Successful output reports that full-plan validation is pending. Review the mapping and funding report, update references in other files, and validate the assembled plan after replacing the fragment. Malformed YAML, recursive aliases, duplicate YAML keys, invalid selections, collisions and local cycles fail with exit status 1 without writing output. Missing command arguments are usage errors (exit status 2).

composite [task_file] output_file [--nested]

Expand YAML !include directives into a standalone YAML output file. Input defaults from TUXFAN_PLANNER_DATAFILE; output is required. Expansion preserves list order, defaults, and multipart definitions without requiring task-schema validation. Input files cannot be overwritten. Long prose is written as > blocks and lists as | blocks. --nested moves plan tasks/milestones/deliverables beneath execution and project dependencies/stakeholders/users/risks beneath resourcing. Values and ID references are retained; ambiguous duplicate locations are errors. See Composite YAML Plans for syntax, examples, and expansion rules.

format [task_file]

Format a data file and its included YAML sources in place. An explicit path overrides TUXFAN_PLANNER_DATAFILE. YAML (.yaml/.yml) uses planner’s built-in style, with no external tool: two-space indentation, long prose as > blocks, multi-line text and lists as | blocks, and collapsed blank-line runs, keeping authored blocks, comments, tags, anchors and explicit nulls. Python (.py) uses Black from planner’s Python environment; install Black with pip install 'tuxfan-planner[format]' (or pip install -e '.[format]' in a checkout).

YAML formatting follows nested !include directives, formats each distinct source once, and preserves directives and file boundaries. Include paths are relative to their containing files. Python formatting operates on one file without executing it; full plan validation is not required. YAML structure/values and include references are checked before saving, and source encoding and line endings are retained. All results are prepared and checked before saving; invalid/missing includes, cycles, or formatter failures leave all sources and backups untouched. Changed files receive numbered .bak backups and are saved atomically; already formatted files remain untouched. Missing dependencies or formatter failures produce an error. Saves are atomic per file, not across the set; a later write failure may leave earlier files formatted. CMake’s format target separately formats planner source code.

spell-check [task_file] [--lang LANGUAGE] [--personal DICTIONARY]

Interactively review prose with the external Aspell executable. The default language is en_US. Install Aspell and a dictionary separately from pip (brew install aspell or sudo apt install aspell aspell-en). The task file can default from TUXFAN_PLANNER_DATAFILE.

Prompts show the file, field, line, context, and numbered suggestions. The exact occurrence under review appears in bold red on color-capable stdout terminals; other occurrences remain unhighlighted. NO_COLOR, TERM=dumb, and redirected output keep context plain. Highlighting does not change source text or text sent to Aspell. Numbered suggestions appear in columns sized to the terminal, capped at max_width columns (80 by default; also the fallback width). Numbers increase down each column, preserving Aspell’s ranking and all available choices. Narrow terminals use fewer columns, and long suggestions wrap. Choose a suggestion number, r to replace manually, i to ignore once, a to ignore for the session, d to add to the personal dictionary, or q to cancel. A final summary and save prompt precede any source/dictionary writes; the default is to discard. An interactive terminal is required. Cancellation before saving leaves staged changes unapplied.

With an English dictionary, valid numeric ordinals such as 2nd, 30th, and 111th do not trigger suffix warnings. Standalone suffixes, malformed ordinals such as 22th, and embedded alphanumeric strings remain subject to normal Aspell checks. Other dictionary languages are unaffected.

Composite YAML is supported, including scalar and list fragments. The include graph is checked before Aspell starts; fields retain their original filenames, lines, and context. Each source string is reviewed once, even when included repeatedly. Text shared between prose and structural uses requires manual review. Ignore-all and dictionary additions span the session. A combined summary groups corrections by file; one final confirmation controls saving.

Checks cover prose in plan metadata, execution narratives, task fields, milestones, deliverables, and risks, including notes. IDs/references, schema keys, dates, funding, enums, and Markdown link destinations are skipped. Source strings are checked once before inheritance or multipart expansion. Valid source syntax is required; full plan validation is not.

Edits preserve comments, quoting, indentation, block styles, line endings, and encoding. Saves validate syntax, retain a .bak backup (numbered when necessary), and atomically replace each changed source. All sources and any explicit or discovered dictionary are checked for concurrent edits before saving. Multi-file and dictionary saves are not one atomic transaction; later failures report the sources already saved. Python files are inspected without execution; computed values, raw strings, concatenated literals, and spellings encoded with escapes may require manual editing. Use a resolved file path when saving through symbolic links. --personal selects an Aspell personal dictionary, overriding discovery; relative paths are resolved from the current directory. Otherwise, the nearest .planner-words.pws in the main input’s directory or its ancestors is used. Without one, Aspell uses its standard personal dictionary. A discovered file must be readable and valid; invalid nearer files do not fall back to ancestors. The selected dictionary is loaded and reported before prompts. Explicit paths can name a new dictionary, created only when confirmed additions are saved. Composite files share the dictionary selected from the main input; included directories do not override it. Selecting a project dictionary replaces the usual personal dictionary while retaining the installed language dictionary. Missing Aspell/dictionaries produce an error. Other commands do not require Aspell.

An example English project word list (use base language en in the header; --lang en_US still selects the spelling variant):

personal_ws-1.1 en 3 utf-8
FleCSI
FleCSolve
Kokkos
list KIND [task_file] [FIELD ...] [--color {auto,always,never}] [--only SELECTORS]

List a top-level plan element using its canonical field name as KIND. Compatibility views activities, workitems, risks, and plan retain their behavior. Each kind has its own help and scoped field choices. Omit task_file when the input environment default is set. See the object-view reference below.

list [task_file] [FIELD ...] [--color {auto,always,never}] [--only SELECTORS]

Without fields, display the full terminal planning document: metadata, fiscal coverage, execution description/activities, milestone and deliverable definitions, and numbered task narratives with category labels and IDs, planning attributes, notes, work items, and risks. Include empty sections and unreferenced definitions. Export settings do not restrict this output. Omit the filename to use the normal input environment default.

planner list --help documents KIND, task_file, and FIELD together under positional arguments. KIND enumerates all supported views, including compatibility views. The primary top-level elements match export.elements:

portfolios
project
priority
managers
pocs
summary
background
fiscal_range_begin
fiscal_range_end
fiscal_years
fiscal_current
planned_value
actual_value
potential_value
execution
milestones
deliverables
tasks

Select one before the filename, for example planner list summary plan.yaml or planner list execution plan.yaml. With a default input, kinds take precedence over field projections. To combine projections, put the filename first: planner list plan.yaml project summary tasks. Prefix filenames matching kind names with ./. Compatibility views remain available and have individual help commands.

Explicit list tasks FILE retains the original compact task-only layout; list plan FILE retains its scoped metadata/relationship summary. With no kind, use list FIELD to specialize output by any supported field identifier, such as label, status, assignees, or mitigation. FIELD is a placeholder for the exact input field name. Combine field names to display several fields. Nested selections retain the activity, task, and item context needed to identify their values. Container names such as workitems show their complete contents. Combine field selection with --only to filter tasks before displaying the requested information. Run planner list tasks --help for supported scoped task fields, or see the field-selection reference below.

The explicit list tasks view prints concise tasks in Word activity order, using the same activity letters, task numbers, and numbered dependencies as the Word export. Parts of a multipart task appear together within each activity, ordered by end date with declaration order breaking ties, including when using label or other field names. Without field names, each multipart group has an unnumbered parent heading displaying its label and ID, such as Airframe Development [AIRFRAME]. Parts are indented beneath the heading, with descriptions and other details one level deeper. The heading appears once per group within an activity, including when --only selects just some parts. Part numbers and dependency references remain unchanged; standalone tasks retain their existing indentation. Each task shows its label and ID in its heading. Children show their source part ID, such as Task A.1: Baseline Design [BASELINE] beneath parent [AIRFRAME]; standalone tasks show their task ID. Expanded child IDs such as AIRFRAME_BASELINE remain the identifiers for dependencies and selectors; local part IDs are not selector aliases. Each heading is followed by its description, a Note: line when present, dependencies when present, and status. Child and standalone IDs use the shared ID styling; closed task IDs remain bold gray and unfunded task IDs use bold muted amber. Field-selected output retains its existing layout. Task labels use normal cyan, with explicit Markdown emphasis preserved. Description text uses canary (#ffff99), including nested descriptions, field projections and configured lines. Explicit configured field colors override this default; descriptions use canary even in closed/unfunded task blocks, whose headings and status fields retain their muted colors. layout.context_colors: false disables this semantic color. If a parent or task heading would exceed the configured width (80 visible columns by default), its bracketed ID moves to a separate line indented two spaces further. Long labels and IDs wrap within the configured width (80 by default); widths account for Unicode characters and exclude ANSI color codes. Notes use the same Markdown rendering and 80-terminal-column wrapping as descriptions, with gray text for closed tasks and muted amber for unfunded tasks. Tasks with funding show identified fiscal years on one line, such as Funding: $500K (FY27), $250K (FY28); dollar amounts are light green when color is enabled. A Funded Total: line at the bottom covers every configured fiscal year, including years with $0K, and reports amounts in thousands of dollars. Every part of an unfunded task entry, including its label, appears muted amber in colored output. Linked activities also show their activity descriptions. Activity and task labels and descriptions interpret inline Markdown: **bold**/__bold__, *italic*/_italic_, and [label](URL). Links display as label (URL); supported schemes are http, https, and mailto. Emphasis uses terminal styles when color is enabled; plain output removes the formatting markers and retains link destinations. Escaped/unmatched markers and underscores within identifiers remain literal. Plain text sections also accept unordered Markdown lists: start each item on its own line with * ``, ``- ``, or ``+ ``. Use a YAML literal block (``|) to preserve those newlines. Items render as bullets, with nested indentation and hanging wraps; inline emphasis and links still apply. Within these sections, consecutive prose lines and indented bullet continuations reflow to the available width. Blank lines separate paragraphs, and nested bullets retain their indentation. This also applies to |- blocks, so prose can be wrapped for readability in the YAML source. Escape the marker (for example, \* ``) to keep it literal. Description and note wrapping counts wide characters as two columns and combining marks as zero, ignoring ANSI styling. Descriptions wrap at 80 terminal columns. List views share one structural hierarchy. Main headings are bold muted cyan, framed above and below by full-width muted orange double rules. Subsections have the same bold muted cyan headings and indented thin gray rules. Activity headings use muted cyan and record titles use cyan; lighter gray item separators and increasing indentation distinguish deeper records. The complete plan groups activities, tasks, milestones and deliverables under Execution, and project dependencies, stakeholders, users and risks under Resourcing. Configured lists retain element declaration order, repeating a parent heading when necessary. Scoped views frame their selected section at the top level. ``list-detail frames its metadata sections and task section too. Rules end at column 80; wrapping accounts for nesting, Markdown, ANSI codes and Unicode widths. IDs retain bold magenta; status/risk/funding colors and explicit configured styles remain in effect, including muted closed and unfunded entries. Field-only selections and the label outline remain compact without structural rules. Color is automatic on compatible terminals; --color and NO_COLOR retain their existing behavior.

label alone gives the compact label outline; other field selections use contextual headings and omit unrelated fields and funding totals.

list-detail [task_file] [--only SELECTORS] [--color {auto,always,never}]

Print validated task details in planner sort order. Ongoing tasks show their funded fiscal years and twelve months of duration per funded year. Empty dependency fields display None. Work item attributes include their labels, IDs, inferred types, statuses, assignees, and descriptions when supplied. Field selection is available only on list. Terminal output uses cyan headings/task labels, blue field labels, subdued magenta IDs and references, canary description text, status colors, and risk severity colors. Funding totals are green. Closed task blocks stay gray; unfunded task blocks use muted amber, with matching bold IDs. The default --color auto honors NO_COLOR, TERM=dumb, and stdout redirection; always and never override detection. Existing text, literal Markdown, ordering, and layout are preserved. Automatic paging retains terminal color behavior. Bash/Zsh/Fish complete the color option.

summary [task_file]

Print task counts by activity and milestone ID (None when omitted). Metadata output includes defined milestone labels, deadlines, descriptions, and deliverables. Funding totals use configured fiscal years, or years inferred from task funding when no plan years are set.

schedule [task_file]

Print dependency-aware task order with COMPLETE, ACTIVE, ONGOING, PLANNING, UNFUNDED, READY, BLOCKED, or CLOSED state. Ongoing task timing follows its funded fiscal years. Planning placeholders remain PLANNING and display Unscheduled until start and either expected or end are supplied; unknown duration displays as Unspecified. Funding estimates do not create their schedule. Closed tasks require only id, label, description, category, and status; they also display Unscheduled until both timing fields exist. Closed tasks use gray list styling; unfunded tasks use muted amber. Tasks without an activity appear under Unassigned in all displays. Top-level project selects only plan metadata; there is no task project field. Work item references appear in task attributes.

import input.docx [output.yaml] [--config PATH] [--update VERSION]

Import visible content from a planner-style Word document into a validated YAML draft. The input filename is required; output defaults to the input path with its final suffix replaced by .yaml, in the same directory. For example, planner import plans/proposal.v2.docx writes plans/proposal.v2.yaml. An explicit output filename overrides this default. Relative paths use the current directory; planner environment overrides are ignored. Input must be .docx and output .yaml or .yml. Existing output files and symlinks are refused. Publication is atomic and exclusive; the source is unchanged.

Missing task IDs use uppercase ASCII label words joined by underscores. Common connectors and routine terms such as development/improvements are omitted; preparation shortens to PREP. For example, Engine Model Development becomes ENGINE_MODEL. Qualifiers remain, without a fixed word limit. Accents normalize to ASCII; labels without usable words fall back to TASK, and numeric labels receive a TASK_ prefix. Recovered explicit IDs are preserved and reserved before allocating generated IDs. Collisions receive _2, _3, etc., in document order, avoiding project dependency IDs and expanded multipart task IDs. Existing local part IDs are retained under the new parent ID. Relationships use the resulting IDs.

Before falling back to planning, missing forecast timing is inferred from positive annual task funding. Missing start uses M1Q1 of the first positive year; missing end uses M3Q4 of the last positive year when no duration was recovered. Recovered dates and durations are preserved. These bounds form one continuous span, including any intervening funding gaps. Allocation parts use their own effective funding and inherited task fields. Report notices and YAML comments identify inferred fields for review. Zero, absent, or placeholder amounts do not provide dates; an aggregate amount alone cannot establish years. Recovered unfunded status is retained when timing can be inferred. Missing status or unrecoverable required timing still becomes planning. Ongoing timing remains funding-driven and actual completion dates are never inferred.

When a selected export omitted a risk’s type, the importer uses technical as a placeholder and records a review notice in the report and draft comments. Explicit unknown risk types fail validation.

The importer detects legacy, asc-v4, and asc-v6 output contracts from Word properties, falling back to recognizable ASC version 6 template headings. Unknown explicit versions are errors. No upgrade is performed unless --update asc-v6 is supplied. This migrates an older draft, adds empty optional resourcing fields, records the target version in YAML comments, and reports missing resourcing/reporting information. Funding-based forecast inference applies to imports with or without this flag. Migration does not supply other missing facts or modify export configuration. Select export.standard: asc-v6 when exporting the resulting draft. ASC v4 is recognized from export metadata or a Project Plan Template (v4) heading. Background prose, existing resourcing information, and milestone reporting levels are retained during --update asc-v6; no facts are invented. Unfilled instructional templates still fail without creating output.

Tasks may be numbered (1., A.1) or lettered (a., A.a, table rows such as a – Name); lettered task numbers are normalized internally; generated task IDs come from labels. A lettered list item starts a task only when it is the next letter in its activity, so i./ii. sub-items stay in the task description. Schedule tables whose fiscal-year cells hold text rather than amounts, and tables with no fiscal-year columns, are kept as review notices.

ASC imports recognize hierarchical task numbers, new table column names, numeric thousands-of-dollars amounts, milestone L1/L2 reporting levels, and external resourcing narratives. Funded/Unfunded is a funding indicator; it does not overwrite a more precise narrative task status. An unfunded task may still have annual amounts. A template without populated task narratives is rejected rather than importing instructional example rows.

Recover metadata, execution narratives, milestones, deliverables, tasks, risk mitigation, and available table attributes and annual funding. Table rows join to narratives by activity/task number. IDs are generated deterministically; deliverable labels resolve references. Optional export options identify custom table headers. Supported inline prose formatting becomes Markdown. Unknown columns and ambiguous work item cells are reported; ambiguous work item text is retained in task notes.

Word’s automatic activity/task numbering and bullet lists are recognized, including inherited list styles. Activity and task labels may be separated from their descriptions by a colon or a spaced hyphen, en dash, or em dash. Funding continuation rows become allocation parts, preserving each B&R and annual amount with review comments. Standalone metadata headings and unbulleted contacts are accepted.

Deliverables and milestones written as text become draft definitions: each bullet, numbered item, or FY27 – text / FY27: text line is one entry with a FIXME_n ID and label for you to rename. A numbered heading followed by bullets (1. Activity A — Workloads) prefixes each item’s description. Deliverables get type: document and status: planning, so drafts do not warn about missing producer tasks. Milestones get a deadline at the end of their stated fiscal year (FY27 → M3Q4FY27), from the item or a preceding FY27 heading; undated milestones use the plan’s first fiscal year and keep their original date text, marked as a placeholder. Other text, such as plain paragraphs, stays in the summary.

Long prose in the generated YAML uses folded > blocks and text with list items uses literal | blocks, wrapped near the configured width (80 by default); short values stay plain. Loading the file gives exactly the imported values.

Top-level YAML fields and activities retain their first-appearance order in the input document. Task entries follow document order in the generated YAML; later CLI views and exports use normal planner task sorting. Blank lines and labeled comment dividers separate top-level YAML fields. One blank line separates list entries containing an id field at every nesting level, including tasks, milestones, deliverables, activities, and work items. The dividers use this format:

#------------------------------------------------------------------------------#
# Milestones
#------------------------------------------------------------------------------#

milestones:
- id: MILESTONES_1
  label: Design review
  description: Review the design.
  deadline: M3Q4FY27

- id: MILESTONES_2
  label: Final review
  description: Review the finished work.
  deadline: M3Q4FY28

Selected Word exports recover visible IDs, references and task fields using semantic paragraph markers. Older or manually authored documents can omit original IDs, multipart structure, task milestone links, dependencies, dates, priorities, and some statuses. Tasks become planning placeholders unless a closed marker or sufficient completion information is available. A completion year alone does not establish a completion month. Funding totals do not establish annual allocations. Missing values and assumptions appear in YAML review comments and the import report, with document block/table-row locations. Review statuses and timing before using the imported plan. Ambiguous deliverable references, unrecognized task structures, and invalid generated plans fail without publishing output.

Unfunded tasks use ANSI color 137 (#AF875F, muted ochre) in terminal listings, and pale amber #E8D5A8 in plan SVG and Gantt SVG/PowerPoint. Closed task entries stay gray, with export fill #D1D5DB.

export [task_file] output_file [--config PATH] [--standard VERSION] [--template PATH]

Configuration export.standard accepts legacy (the unchanged default), asc-v4, or asc-v6. V4 defaults to normal spacing, underlined headings, portrait tables, and v4 content/column order. Explicit selections and layout settings override profile defaults. See Export Options for examples. Use export.standards.<standard> for per-standard overrides of shared export settings. Layout mappings merge; content selections and ordered lists replace. All blocks are validated, including inactive ones. Examples are included in planner fields config.

--standard legacy|asc-v4|asc-v6 overrides export.standard for this invocation and selects the corresponding configured rules. Without it, the configured standard remains the default. The option applies to Word, PDF, SVG, and PowerPoint export; it does not modify configuration or plan files. All configuration blocks remain validated, including inactive ones. For example:

planner export plan.yaml plan-v4.docx --config configs/asc.yaml --standard asc-v4

Task input accepts start with either expected (inclusive months) or end (inclusive fiscal period). line: [start, end] displays effective dates for either input form; redundant supplied duration/end values must agree.

In configured task lines, {field: number, format: short} prints a bare number such as A.1.1; format: full (the default) retains Task ``. This changes presentation only, preserving IDs, numbering, and table output. See :doc:`export-options` and ``planner fields config for the YAML syntax.

Formatting instructions accept boolean heading beside a standalone field, as a grouped-line default, or on an individual line field. For example, - {description: null, heading: false} hides Description:. Standalone field labels are enabled by default, including descriptions. Structured-field instructions apply the setting to the parent and selected child labels; section titles and table headers are separate.

Write a Word plan for .docx, an SVG plan for .svg, a PDF plan for .pdf, or editable PowerPoint plan slides for .pptx. PDF export converts the same Word document using Microsoft Word, preserving its pagination and formatting. It requires Word installed and activated on macOS or Windows, and may prompt for automation permission on macOS. macOS conversion files are staged inside Word’s own sandbox, avoiding per-export file-access requests. Planner copies the finished PDF to the requested destination and removes temporary files. Windows uses a temporary folder beside the output. Word remains open after conversion. Word versions and installed fonts can affect pagination, as with a manual PDF save. Conversion failures leave an existing PDF unchanged. On Linux, export .docx and save as PDF in Word on a supported system. PDF accepts the same export options, custom table labels/alignment as Word. Merged activity and parent-task table rows have horizontal padding to keep their labels clear of cell borders. Activity headings stay with their first task row across page breaks; multipart parent headings stay with their first part. Parent headings throughout Word/PDF narratives and PowerPoint continuation slides likewise stay with their first child where space permits. Explicit page/section boundaries remain intact, and larger sections can continue. Word/PDF tables size all columns from their displayed words and bold headers, keeping B&R codes and values such as Unfunded together where space permits. Multiword text can wrap between words. Export warns when estimated minimum widths exceed the page; orientation, margins, and font size remain unchanged. Configure narrative text with export.layout.font_size and Word/PDF table text independently with export.layout.task_table.font_size. Sizes are numeric points in half-point increments, from 1 to 1638. Word/PDF defaults are 12 pt for body text and 10 pt for tables. Omitted body sizing preserves SVG/PowerPoint native sizes; explicit sizing adjusts their wrapping and pagination. Display titles and markings retain their sizes. Table left/right cell margins are 2.7 pt per side, or 3 pt for merged activity/parent rows.

Set export.layout.spacing to normal for reference-document paragraph spacing or tight (the default) for the compact layout. The setting applies to Word/PDF, SVG and PowerPoint exports, with pagination adjusted as needed. Following portrait tables, Word/PDF inserts an 8 pt paragraph gap in normal mode or 4 pt in tight mode; cell spacing and explicit page breaks are retained. It does not affect terminal list or Gantt chart spacing. The output-standard identifier is retained in metadata and is not printed in exported content.

Example: planner export tasks.yaml plan.pdf --config options.yaml. Word narratives identify closed tasks with a gray [CLOSED] marker. SVG export warns when task IDs produce empty or duplicate SVG element IDs, including conflicts with its dependency marker. Export still completes with the existing IDs. Warnings name the tasks and include source locations when available. Only SVG plan export emits these warnings; validation, Word, and Gantt exports are unaffected. export.elements in the general configuration selects fields through nested boolean mappings. Task narrative fields and table columns are selected independently. task_table controls Word/PDF columns and totals. export.layout.task_table controls presentation without enabling content. Risk and mitigation appear within task narratives, without a separate mitigation section. Narrative notes use elements.tasks.note; the retired note flag and legacy export option keys are rejected. Omitted/null elements enables everything; bare entries enable individual fields or branches, and an empty mapping selects no content. Full-plan validation and calculations remain unchanged. See Export Options for the complete tree and migration instructions. --config PATH selects a complete config.

PowerPoint exports editable plan slides without requiring Office. Templates (template.pptx or template.potx) are searched in TUXFAN_PLANNER_TEMPLATE_DIRECTORY, then the current directory; otherwise the built-in design is used. --template PATH selects a specific .pptx/.potx file using a current-directory-relative or absolute path, bypassing template search. Missing or invalid files are errors. This option requires .pptx output. See Export Options for template setup and slide formatting details.

Example: planner export tasks.yaml plan.pptx --config options.yaml.

export-gantt [task_file] output_file [--from PERIOD] [--through PERIOD]

Write a fiscal-month Gantt chart. Use a .svg output path for a vector image or .pptx for slides with editable PowerPoint shapes. PowerPoint output uses one or more slides, split by activity, row count, and long time ranges. Bars use the stated start and an end month calculated from the expected duration, counting the start month as month one. Ongoing tasks instead have full-year bars for every year with positive funding, leaving gaps for missing or zero-funded years. Each task row keeps its number and label on one line when they fit, otherwise wraps the label at a word boundary within the two-line cell. Arrows leave the dependency bar’s right edge and enter the dependent bar’s left edge, routing around overlapping bars without bending past the farther bar’s right edge. They connect bars within an activity; PowerPoint shows an arrow when both bars are on the same slide. The optional inclusive bounds accept whole fiscal years, such as FY26 through FY27, or exact periods, such as M1Q1FY26 through M3Q2FY27. Fiscal years expand to their first or last month. Tasks outside the range are omitted, and overlapping bars are clipped. Without bounds, the axis covers the configured fiscal year range exactly. If no fiscal years are configured, it covers task and completion dates. A supplied bound overrides that end of the default axis.

completion [bash|zsh|fish]

Print a shell completion script.

All three shells add .yaml and .yml plan input suggestions from TUXFAN_PLANNER_DATA_DIRECTORY alongside local filenames. Suggestions use relative names and support spaces and nested directory navigation. The directory setting is read each time; no plan is loaded or validated. Unset, missing, or unreadable directories add no suggestions. Absolute paths use normal local completion.

Data-directory candidates appear only at plan input positions, including the first argument to merge and split. Output paths, export-options paths, personal dictionaries, option values, and fields after the input retain normal completion behavior. When TUXFAN_PLANNER_DATAFILE supplies the input for export, export-gantt, or composite, their first filename is treated as an output, so data-directory candidates are not added there.

completion install

Configure completion on virtual environment activation for Bash, Zsh, and Fish. Run using the environment’s Planner, then reactivate it. Existing activation scripts receive managed hooks and numbered backups; repeated installation updates hooks without duplicating them. Zsh initializes its completion system if needed. Shell startup files are unchanged. Reinstall hooks if the environment is recreated. Completion definitions remain after deactivation. CMake’s install-editable target performs this setup automatically. After a planner update, reactivate the environment or reload the generated script to refresh rules already loaded in the current shell. The installer updates activation hooks; it cannot change its parent shell’s loaded rules.

Object List Views

Use list [task_file] for the full terminal planning document. list KIND [task_file] [FIELD ...] selects scoped objects. Each kind uses its own schema fields; shared names such as status or label refer only to the requested objects. Identity headings are retained when selecting fields.

  • portfolios, project, managers, pocs, summary, background, fiscal_range_begin, fiscal_range_end, fiscal_years, fiscal_current, planned_value, calculated actual_value and potential_value, dependencies, stakeholders, users, risks: display the selected metadata field, with None for absent values. Preserve ordered lists and normalize fiscal years. Each accepts its own name as a field/filter target.

  • execution: description and activities, including empty activities. Relationship filters select the execution element as a whole.

  • tasks: task input fields. Without fields, preserve the activity-grouped, numbered task layout and selected-task funding totals.

  • milestones: milestone fields plus tasks (historically associated), direct_tasks, producer_tasks (required through outputs), and required_tasks (current direct/output requirements).

  • deliverables: deliverable fields plus producers, ready, required_by. Default output distinguishes actual, inferred, deferred, withdrawn, blocked, and awaiting-acceptance states.

  • activities: section fields plus tasks, task_count, funding. All declared activities are included even when empty; Unassigned appears when tasks have no section. Funding uses configured years, including zero totals, or infers years from funding. Multipart parent budgets count once per activity.

  • workitems: workitem fields plus tasks and derived type (workitem/mr). Deduplicate by ID, merging owners for identical metadata. Conflicting metadata stays in owner-labeled variants.

  • risks: risk fields plus tasks. Keep each entry with its owning task.

  • plan: plan metadata, execution description and activity narratives, and concise task/milestone/deliverable relationship summaries.

For example:

planner list tasks data/tasks.yaml --only status=planning
planner list deliverables data/tasks.yaml label status ready required_by
planner list deliverables data/tasks.yaml --only type=document
planner list milestones data/tasks.yaml --only deliverables=NEEDS
planner list activities data/tasks.yaml label task_count funding
planner list workitems data/tasks.yaml --only status=open
planner list risks data/tasks.yaml --only level=high
planner list plan data/tasks.yaml

Object views filter the requested objects rather than selecting tasks first. Every kind accepts native field targets and related tasks, activities, tags, milestones, deliverables, and workitems. Relationship values match IDs or labels (workitems match IDs). Singular relationship aliases work; producer and producers alias tasks. TARGET=VALUE matches exact values; TARGET~VALUE matches literal substrings within that target. Bare values match substrings across searchable fields. Matching ignores case, and whitespace is trimmed. Values within one flag are OR alternatives; repeated flags are AND requirements. Unknown fields or targets are usage errors. Scoped derived view fields do not extend the plan input schema.

For example:

planner list tasks data/tasks.yaml --only 'id~HARD'
planner list tasks data/tasks.yaml --only 'id~HARD,SOFT' --only status=active
planner list deliverables data/tasks.yaml --only 'label~report'

id~HARD matches HARD_DEVELOPMENT, HARD_SUPPORT, and SOFTWARE_HARDENING. Matching is literal, without regex or glob syntax. The first = or ~ separates target and value; later operators are literal characters in the value. =~ is not a separate operator: label=~draft matches the exact label ~draft. Substring target selectors apply only to explicit list KIND commands; legacy list and list-detail selectors remain unchanged.

Task id= filters compare against both expanded task IDs and their multipart parent IDs. --only id=ASSEMBLY selects all parts of that parent, while --only id=ASSEMBLY_A selects only the exact expanded task. Standalone IDs remain exact matches. Exact matching ignores case and trims whitespace, without matching prefixes or local part IDs. id~TEXT searches expanded and parent IDs for substrings. Parent selectors combine normally with comma alternatives and repeated filters; selectors continue to use expanded child IDs. Default task output retains full-plan numbering and counts parent funding once. This applies to explicit list tasks; the legacy shorthand’s selectors are unchanged.

Unreferenced definitions and empty activities remain visible unless filtered. Computations use the full plan before filtering; selecting one producer does not change shared-output readiness. Shared workitem filters must match within one metadata variant; selected IDs retain all variants so conflicts stay visible. Output shares terminal Markdown, links, wrapping, colors, NO_COLOR, and paging with task lists. IDs in identity headings and reference fields use bold standard magenta; closed task entries retain bold gray IDs and unfunded task entries use bold muted amber IDs. This also applies to legacy field projections, multipart parent IDs, and workitem ID fallback labels. Ordinary prose is not highlighted merely for mentioning an ID. Wrapping uses visible text, so ID highlighting does not change line widths. Color controls and redirection behave as usual. Bash/zsh/fish completion includes kinds and scoped fields.

Multipart references in task relationship lists use parent:child, for example, Baseline Design [AIRFRAME:BASELINE]. Milestone task lists, deliverable producers, activity tasks, workitem owners (including metadata variant headings), risks, and plan task summaries share this display format. Underscores inside either ID are preserved. Task labels in relationship lists use normal cyan. YAML IDs, dependency references, and selectors retain the expanded AIRFRAME_BASELINE form; colon references are not selector aliases. Normal grouped task headings continue to show source part IDs below the parent.

In list plan, activities appear in declaration order with numbered label headings (1: Section label), followed by indented ID: and Description: lines. This also applies to list plan ... execution.

Task relationship fields display a heading followed by one indented, hyphen-bulleted task per line, including when explicitly selecting fields. This applies to tasks, direct_tasks, producer_tasks, required_tasks, and producers in all object views. Each reference wraps independently at the configured width (80 visible columns by default); empty lists display None. For example:

Tasks:
  - Baseline Design [AIRFRAME:BASELINE]
  - Advanced Design [AIRFRAME:ADVANCED]

Legacy list [task_file] FIELD ... retains cross-context projections and its existing task selectors. With a default input, list deliverables now selects the definition view; use list plan.yaml deliverables for the old projection. A filename equal to a kind can be qualified, for example ./tasks.

Filtering List Output with --only

Legacy list and list-detail accept --only [TARGET=]VALUE,.... Quote values containing spaces:

planner list tasks.yaml --only tags="Tag1, Tag2"
planner list-detail tasks.yaml --only milestones="Flight Deliverables"
planner list tasks.yaml --only milestones=FLIGHT_DELIVERABLE
planner list tasks.yaml --only activities=Aircraft --only tags=gpu
planner list tasks.yaml label --only tags=gpu
planner list tasks.yaml --only "aircraft, gpu"

Targeted Matching

A target= prefix restricts matching to one field. Targeted values match complete values and ignore case:

  • activities: activity names, generated labels such as Activity B, or activity IDs.

  • activities: activity IDs and labels; native task activity selects an ID.

  • tags: task tags only.

  • milestones: milestone IDs or their display labels, including indirect links through outputs.

  • deliverables: output IDs or display labels; matches their producing tasks.

Singular aliases (activity, activity, tag, milestone) also work. For example, tags=gpu matches the tag GPU, but does not match gpu-kernels or a milestone named GPU. Milestone matching includes references inherited by multipart parts.

Bare Text and Combining Filters

Without a target prefix, values match substrings across all the fields above. For example, --only "aircraft" can match a milestone ID containing AIRCRAFT, an activity named Flight Development, or a task tag containing aircraft. These matches ignore case and trim surrounding whitespace; they use literal text rather than regular expressions or wildcards.

Values separated by commas within one --only are alternatives: any value may match. Repeating --only narrows the result: all flags must match. For example, --only activities=Aircraft --only tags="gpu, checkpoint" requires the Aircraft section and either the gpu tag or the checkpoint tag. Bare and targeted flags can be combined, such as --only aircraft --only tags=gpu. Unknown targets and empty value lists are usage errors.

Only matching tasks and their associated activities appear. With list --only, activity headings show only IDs and labels, omitting activity descriptions. Activity letters, task numbers, and dependency references retain their full-plan values. Referenced dependencies are not automatically included. list-detail also limits activity and milestone metadata to the selected tasks. Omitting --only displays all tasks. An empty selector list is a usage error; unmatched selectors produce a no-matches message and zero totals for configured years, except that field selection omits totals. This option applies to the two list commands, not exports.

Selecting Fields in Legacy List Output

In list FIELD, replace FIELD with any supported canonical input field identifier. Use its exact spelling, including underscores. For example:

planner list plan.yaml label
planner list plan.yaml status assignees --only tags=gpu
planner list plan.yaml mitigation --only activities=Solver
planner list plan.yaml workitems
planner list plan.yaml activity funding

Names combine their selections; repeating a name has no additional effect. Without field names, ordinary list behavior is unchanged. These selections are available only on list, not list-detail or exports.

Supported fields are grouped below by their source. Shared names are written only once on the command line and select all applicable levels:

Field names

Source

Fields

Plan

portfolios, project, managers, pocs, summary, fiscal_range_begin, fiscal_range_end, fiscal_years, milestones, deliverables, execution, tasks

Task

id, label, activity, description, note, site, bnr, funding, type, tags, start, end, expected, completed, priority, status, dependencies, funding, milestones, deliverables, risk, workitems

Work item

id, label, description, status, assignees

Risk

type, level, description, mitigation

Deliverable definition

id, label, description, type, status, completed

Milestone definition

id, label, description, deadline, deliverables

Execution narrative

description, activities

Activity

id, label, description

Names retain input spelling, including underscores: use activity, not --activity. Abbreviations, input aliases, computed fields such as --end, internal names such as --risks, and arbitrary metadata keys are not accepted. Composition directives such as defaults and parts are applied during loading and are not selectable model fields. The former --labels flag is removed; use label.

Context for nested fields

A nested selection includes the activity, task, and item identity needed to interpret the value. For example, assignees can display:

Solver Development [solver]
  Task: Update solver [SOLVER_UPDATE]
    Work item: GPU memory management [aircraft/design#42]
      Assignees: designer_one, designer_two

mitigation identifies the risk by type and level beneath its task before showing mitigation text. status shows both task and work item statuses. description selects task, activity, risk, work item, and milestone narratives. type selects task/risk types; a work item’s inferred type is not an input field and is not selected.

A container name such as risk or workitems displays its full contents. Combining it with a child name does not duplicate that branch. tasks displays all fields of selected, expanded tasks. milestones also shows top-level milestone definitions and task milestone references. execution, activities, and description access the separate execution narrative; ordinary activity context uses task grouping as before.

Fields are rendered in schema order, with activity/task ordering preserved and work items in input order. Identity fields already present in headings are not repeated. Missing or empty requested values display None. Branches without any requested field are omitted; if none apply, output is No selected fields are present. Long values wrap at the configured width (80 by default). Inline Markdown and color controls apply, with unfunded task branches muted amber. Explicit --color always overrides automatic detection, including NO_COLOR.

Compact label outline

label alone retains the compact activity/task/work item outline:

Solver Development
  Update solver
    GPU memory management
    aircraft/design!69
  Validate solver

Tasks are indented two spaces and work items four. Work items without labels use their IDs. This compact form omits plan/milestone metadata, generated numbers, and field prefixes. Adding other field names uses the contextual format described above. An empty plan without filters produces an empty label outline.

Filtering and omitted output

--only selects tasks first. Each selected task retains its work items; only activities containing selected tasks appear. Milestone definitions and explicitly selected activities are limited to those referenced by selected tasks. Without filters, all plan-level definitions remain available. The supported selector fields do not change: task labels and work item labels/IDs are not additional search fields. A targeted filter can still use activities=Activity B even though field-selected output omits numbering. Repeated filters remain AND requirements, with OR alternatives within a flag.

Field-selected output omits unrelated fields, separator rules, generated numbering, and funding totals. An unmatched filter prints only No tasks match --only.

Funding Totals for Filtered Lists

Fiscal-year totals use the selected tasks:

  • A standalone task contributes its own funding.

  • If a multipart parent specifies funding, its full budget contributes once when any of its parts match. It is not prorated, counted repeatedly, or added to part-level amounts, even if matching parts override funding.

  • Without parent funding, only matching parts contribute their own amounts.

For example, a parent with FY27: 300K contributes 300K whether one or several parts match. Without that parent budget, matching parts with 100K and 50K contribute 150K. Every configured fiscal year remains in totals, including zero-funded years. Individual task funding lines continue to show the task’s explicit or inherited funding. These funding lines and totals are omitted whenever list field names are supplied.

Run planner list --help or planner list-detail --help for command-line examples and a description of the matching and funding rules.

Environment Variables

TUXFAN_PLANNER_RATES_FILE

Overrides configuration rates_file for staff-funded labor. Relative paths use the working directory; an empty value leaves configuration active. Rates load only when staff allocations need them. See Funding and Staff Costs.

TUXFAN_PLANNER_DATAFILE

Default plan file. When set, basic commands can omit task_file and export commands and composite can pass only the output path. An empty value behaves as unset: an explicit input filename is required, and output-only commands do not infer an input. Missing input produces a normal usage error (exit status 2).

TUXFAN_PLANNER_PAGER

Optional pager executable and arguments for long interactive output, such as less -R. Unset/empty values disable paging. This does not choose a data file or affect exported files. See the paging behavior above.

TUXFAN_PLANNER_EDITOR / EDITOR

Editor executable and arguments for add and edit. The planner-specific setting takes precedence; unset, empty or whitespace-only values fall back to EDITOR. At least one usable setting is required. Quoted paths and arguments are parsed without a shell. GUI editors must wait for the buffer to close, for example code --wait.

TUXFAN_PLANNER_DATA_DIRECTORY

Directory used for every relative plan filename, including the default from TUXFAN_PLANNER_DATAFILE. It takes precedence over the current directory; if the file is missing there, the same relative filename is tried in the current directory. Existing invalid or unreadable inputs do not trigger fallback. The configured path must be an existing directory when resolving a relative input. Absolute inputs bypass it, and an empty value behaves as unset. Home-directory notation (~) is expanded. Setting only the directory does not choose a default file: pass a filename or also set the data-file variable. The setting applies to read, edit, export, composite, format, spell-check, merge, and split inputs. Output and export-options paths retain their current-directory semantics; !include paths retain containing-file semantics.

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
export TUXFAN_PLANNER_DATAFILE=tasks.yaml
planner validate

This checkout provides fictional jet-airplane development fixtures under data/; see Development Data.

TUXFAN_PLANNER_TEMPLATE_DIRECTORY

First directory searched for template.pptx or template.potx by PowerPoint plan export. An empty value is unset; ~ is expanded and relative paths resolve from the current directory. The directory must exist. The current directory is searched next, then the built-in design is used. This setting does not affect export-gantt or other formats.

XDG_CONFIG_HOME

Absolute base directory for user configuration; defaults to ~/.config. See General Configuration for initialization, validation, and migration.

The help and usage messages show whether each planner environment variable is set and display its current value when set. Run planner --help to check them. On compatible terminals, variable names are bold and only the displayed value (including quotes) is green when set. Purpose text, set to, and not set remain plain. Wrapped values retain their color; explicitly empty values display green ''. Redirection, NO_COLOR, and TERM=dumb disable these styles. Empty-value resolution rules remain as documented above. Ill-formed commands print an error and the relevant command help to stderr, then exit with status 2.

Exit Status

  • 0: the command completed successfully. Validation warnings do not make a valid plan fail.

  • 1: validation or another command operation failed. Diagnostics go to stderr.

  • 2: command-line arguments are invalid or required arguments are missing.

Examples

planner validate planner/examples/tasks.yaml
planner list planner/examples/tasks.yaml
planner list planner/examples/tasks.yaml label
planner list planner/examples/tasks.yaml status mitigation
planner list planner/examples/tasks.yaml label --only activities="Planning System"
planner list-detail planner/examples/tasks.yaml
planner list planner/examples/tasks.yaml --only "architecture"
planner list-detail planner/examples/tasks.yaml --only "Design"
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 validate /tmp/expanded.yaml
planner export planner/examples/tasks.yaml /tmp/plan.docx
planner export planner/examples/tasks.yaml /tmp/plan.svg
planner export-gantt planner/examples/tasks.yaml /tmp/gantt.svg
planner export-gantt planner/examples/tasks.yaml /tmp/gantt.pptx
planner export-gantt planner/examples/tasks.yaml /tmp/fy26-fy27.svg --from FY26 --through FY27
planner export-gantt planner/examples/tasks.yaml /tmp/partial.pptx --from M1Q1FY26 --through M3Q2FY27

With default input and export options:

export TUXFAN_PLANNER_DATAFILE=planner/examples/tasks.yaml
# Planner initializes the default user configuration automatically on first use.
planner validate
planner list label
planner composite /tmp/expanded.yaml
planner export /tmp/plan.docx

Input Integrity

Task IDs, labels, and descriptions must be non-empty strings. Execution-section links are optional; all unlinked tasks appear under Unassigned. Use quoted strings for numeric IDs. YAML plan and export-option files reject duplicate explicit keys with a source filename and line number; explicit values may still override values inherited through YAML merge keys (<<).

Only documented fields are accepted in every input mapping. Unknown fields raise generic errors regardless of whether the name was supported previously. Funding is the sole budget input; the optional Word Funding column shows a computed task total. Filters support activities, tags, and milestones.

Deliverable inspection

fields deliverable prints the output schema; avail deliverables.type prints paper, document, presentation, release, software, dataset, model, service, training, demonstration, assessment, design, and hardware. show FILE deliverables.type collects types used in a plan. list FILE deliverables selects definitions and references. list-detail and summary show readiness, required-by dates, and producers; schedule shows task references and required-by dates. validate counts deliverable definitions and warns about missed milestone deadlines, unknown required timing, and required outputs without producers. See Plan Schema for the all-producers rule and legacy prose migration.

Deliverable status defaults to required. planning defers assessment, closed removes the requirement, and explicit complete fulfills it without requiring producer completion. Direct task requirements remain. References retain non-default status annotations, and detail/summary/plan exports distinguish deferred, no-longer-required, complete-with-unknown-date, and inferred-complete outputs. Optional completed requires status: complete and records an actual fiscal period for historical deadline checking. show FILE deliverables.status and avail deliverables.status inspect stored states and allowed choices; templates comment out completed because the default status is required. Historical relationship filters and summary counts remain available for every status.

blocked outputs remain required with an obstacle. submitted outputs are awaiting acceptance and remain outstanding. Both retain producer/deadline checks, including missing or undated producers. Completed producers do not implicitly unblock or accept these outputs. Detail/summary and Word/SVG output label those states explicitly; references annotate them as [blocked] or [submitted]. Both are available in templates, show FILE deliverables.status, and avail deliverables.status. completed remains exclusive to complete outputs.

The document deliverable type describes material that does not require submission, such as internal documentation. It may be marked complete directly. paper describes a paper intended for submission.

General Configuration

planner config init [--config PATH] creates a complete user configuration from the packaged default without overwriting any existing file. The default is ~/.config/tuxfan-planner/config.yaml (honoring XDG_CONFIG_HOME). A missing implicit default is initialized automatically on first operational use.

--config PATH is accepted before or after every command, including scoped list commands. Explicit missing files and existing invalid/unreadable files fail with exit status 1. Configuration is YAML and contains config_version, task_priorities, task_categories, and export. Optional sites and bnrs are ID-only allowlists. Tasks accept one site and one B&R ID; type accepts one built-in ID or a list of IDs: labor, contract, equipment, services, nonlabor. The former configuration types section is rejected; remove it from existing configurations. Omitted site/bnr sections leave those fields unrestricted; empty lists permit only empty task values. Exports display these IDs. avail site and avail bnr display configured choices; avail type displays the built-in types. The old --export-options argument is removed and its environment variable is ignored.

Tasks optionally specify one scalar priority ID from task_priorities. Omitted/null/empty text means unassigned; IDs are trimmed and matched exactly. Defaults and parts inherit, replace, or clear the value. Lists and unknown IDs are rejected. list tasks FILE priority and --only priority=capability operate on task assignments. avail priority lists configured IDs and show tasks.priority lists used IDs. Category remains a required single ID. There is no project priority element or calculated primary priority. Terminal task displays use configured category and priority labels, including explicit field projections, configured lines, list-detail, and schedule. List views and list-detail append the canonical ID in brackets, for example Essential delivery [DELIVER]. The bracketed suffix uses light cyan (ANSI 96) when colors are enabled, including configured lines and explicit projections. Missing priorities and mixed parent summaries retain None/Mixed without IDs. Export task narratives use configured labels. Word/PDF task tables use optional table_entry values from task_categories and task_priorities, falling back to canonical IDs unchanged. No automatic CAT/ASC conversion is applied. avail category and avail priority also show explicit table labels. This is presentation only: plans, validation, filters, show, avail, and templates continue to use canonical IDs. Word import resolves the display labels or explicit table values back to configured IDs. Table IDs disambiguate duplicate priority labels; without enough information, import requires review. See General Configuration for the full file format and migration instructions.

Default Full-Plan Listing

Unqualified list FILE and default-input list render every plan element, independently of export.elements and export.layout. Notes present in source are shown. Existing field projections, including list FILE summary tasks, keep their established behavior.

Unqualified --only retains task-filter matching. It restricts task narratives and related activities/milestone/deliverable definitions; metadata, readiness, and references retain full-plan context. No matches retains the existing notice and zero funding totals. Use explicit kinds for native object filters. Full output uses the standard color/Markdown/wrapping/paging behavior.

Project-Year Funding

Plans may declare fiscal_current: FY27 and planned_value: $100K. The year is explicit, independent of today’s date and fiscal coverage. A planned value requires a current year; amounts use funding syntax and display in dollar-prefixed thousands. actual_value is read-only current-year funded task funding across the full plan: every status except unfunded, with authoritative parent budgets once. potential_value adds unfunded tasks and is never budget-colored. Both measure allocations, not expenditures. It remains a complete-project total in filtered list output. Missing fiscal_current means unavailable; missing yearly funding means zero; missing planned value means a neutral comparison.

Use planner list fiscal_current plan.yaml, planner list planned_value plan.yaml, planner list actual_value plan.yaml, planner list potential_value plan.yaml, or planner show plan.yaml actual_value. Metadata and legacy projections also accept these names; show remains plain text. List Actual Value amounts are green below plan, black at plan and red above plan, subject to --color, redirection and NO_COLOR. Configured list.elements and export.elements accept each name independently, including per-standard export rules. actual_value and potential_value are rejected in authored plans and recomputed on Word import; planner fields plan shows the two inputs and fields config shows the output selectors.

Configured List Presentation

An optional general-configuration list.elements tree controls terminal selection, ordering and styled repeated lines independently of exports. Without it the existing list layouts are retained. Explicit kinds request their scope even when configuration omits it; explicit positional fields use the existing projection and override configured selection/layout. --only still filters objects using the complete plan.

Ordered task, milestone, and deliverable instructions use the same boolean heading controls as exports, including line defaults and per-field overrides. Omitting the setting retains the existing terminal field labels.

Configured lists may add a totals element: plan-wide funding totals, printed at the element’s position in list.elements like any other element. A bare totals: prints Funded Total. Its optional activity and bnr children add, in order, each activity’s B&R rows and activity total, then the plan-wide B&R rows, before Funded Total. Regular totals always exclude unfunded budgets. The unfunded child adds a separate Unfunded Total: immediately before Funded Total: using the same formatting as the other subtotals (planner list totals FILE unfunded). This replaces its previous behavior of including unfunded amounts in totals.

Totals print as a table: one row of fiscal years, then a two-line pair per total, with its bold magenta label and trailing colon on the first line and its green amounts on the second, left-aligned under their years in equal eight-character columns, separated by three spaces. The grid sits at the right edge: the widest final-column year or amount ends at the delimiter, without trailing spaces. The Activity A portion uses cyan record-title coloring. A rule sets Funded Total apart from the subtotals. B&R labels use Activity A B&R CODE Total: within activities and B&R CODE Total: for plan-wide totals. When the years do not fit in the configured width (80 columns by default), the table repeats in consecutive blocks of years:

════════════════════════════════════════════════════════════════════════════
Totals:
════════════════════════════════════════════════════════════════════════════
                                                 FY27       FY28       FY29
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Activity A Total:
                                                 $260K      $260K      $260K
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Funded Total:
                                                 $4945K     $2710K     $360K

Configuration example:

list:
  elements:
    project:
    tasks:
      - line: [label, id, status]
      - description:
    totals:
      activity:
      bnr:
    deliverables:

Totals cover the tasks the list shows, so --only filters them. Declaring totals replaces the Funded Total: line that a bare tasks element prints; without it, that line is unchanged and custom task layouts print no total. totals is computed, not a plan field, and is not an export element (export tables use task_table.totals with the same activity, bnr, and unfunded children; table activity also accepts top or bottom). Bare/true table totals shows only the overall total; false or an empty mapping disables it. Legacy table siblings totals_activity, totals_bnr, and totals_unfunded remain supported with boolean/bare totals, but cannot be mixed with a totals mapping. Totals print one amount per plan fiscal year, so a plan without fiscal_years (or a fiscal range) prints none.

planner list totals FILE prints only the totals table, without the section heading. Name activity, bnr, or unfunded to choose breakdowns, for example planner list totals FILE bnr; otherwise a configured totals element’s choices apply, and the default is activity and B&R subtotals. --only takes task filter targets and sums only the matching tasks:

planner list totals plan.yaml
planner list totals plan.yaml activity
planner list totals plan.yaml bnr --only activity=WINGS

Use planner list plan.yaml --ignore-config to print complete records while bypassing configured list presentation. Scoped kinds and explicit fields/filters remain honored. Classification vocabularies and allowlists still load for validation and labels. --config and --ignore-config are mutually exclusive regardless of position; other commands reject the bypass option. Subcommand help and bash/zsh/fish completions include it. See General Configuration for examples.

Metadata presentation

Use portfolios (plural) in plans, list/show fields and export selections. portfolios, managers and pocs accept scalar text, YAML sequences, and literal/folded Markdown lists. fields config includes examples of export.layout.context_colors and list.layout.context_colors and the optional layout.metadata heading/value controls. These styles do not alter content inclusion. Explicit field selections retain the active list color policy; --ignore-config bypasses list presentation settings.

Activity migration

fields activity prints an id-first activity mapping; insert it under execution.activities. fields execution prints the containing mapping. The former fields section and execution.sections names are rejected. show execution.description and show execution.activities.id use the new schema. Task references and selections use activity.

list activities displays every declared activity, including empty entries, and a generated Unassigned group when needed. Activity letters follow complete plan declaration order and survive task filtering. Use --only activities=ID for relationships, or task --only activity=ID for the native reference. Configured lists support ordered formatting under execution.activities; --ignore-config retains complete native output.

Execution description formatting

fields config shows an optional ordered execution layout for export and configured list output. Under elements.execution, use - description: with sibling heading: false to retain execution prose without its description heading. Add - activities: to retain activity definitions. Omitted or true heading uses the default visible description heading; the standard’s top-level Execution heading is independent. The existing mapping syntax remains valid.

Alternatively, use the concise mapping execution: {description: {heading: false}, activities: null}. The description style accepts only a boolean heading control. fields config includes examples of both supported forms.

Scoped export spacing

fields config shows optional collection spacing settings. Under export elements, tasks/milestones/deliverables accept spacing: normal or tight in mappings, or a standalone spacing instruction in their ordered format lists. Execution and its description/activities, summary/background, resourcing prose and multi-value metadata support the same override. Omission inherits the nearest parent setting or export.layout.spacing. Spacing-only entries retain default content; explicit field exclusions remain effective. Table cell formatting and terminal list presentation stay independent.

Generated-number headings

Exports and configured lists print generated task/activity heading numbers with a colon before the following label, including multipart children and short numbers: Task A.1.1: label or A.1.1: label. A line: [number, label] instruction uses this separator automatically. Number-only table cells and stable IDs remain unchanged. Gantt task labels follow the same convention.

Project Dependency and Risk Views

list dependencies [task_file] [FIELD ...] lists project commitments with promised fiscal dates, linked project risk IDs, and referencing tasks. list risks [task_file] [FIELD ...] lists both reusable project risks and private inline task risks. Project risks appear first; inline entries identify their owning task. --only scope=project and --only scope=task restrict risk ownership scope. Other native fields and task relationship filters retain the usual matching rules. Risk headings are unnumbered and severity-colored.

fields dependency (or fields dependencies) prints a commitment template. fields project-risk (also fields risks) prints a project risk template; fields risk continues to print a private inline task risk template. fields plan includes both structured collections. fields config includes the new content selections and an ordered risk-format example.

avail dependencies.type prints internal, external. avail risks.type prints the five project risk classifications; avail risk.type retains the same choices for inline task risks. show FILE dependencies.promised and show FILE risks.id inspect project definitions. CLI help and shell completions include these fields and template kinds.

schedule keeps task-to-task ordering and cycle checks. A project dependency is a commitment, not a task node. An otherwise-ready pending task with such a reference stays BLOCKED, with its delivery shown as unconfirmed. A promised date passing does not establish delivery. Starts before a promised month issue source-located warnings; starts in the same month are allowed. Dates are not rescheduled. Explicit task statuses retain their existing behavior.

The plan/configuration prose names request_dependencies and external_risks are replaced by structured dependencies and risks. Legacy Word prose is preserved in summary text with review notices; migration does not invent facts.

Parent summaries in task lists

planner list tasks plan.yaml --parents collapses matching multipart parts to a parent summary and retains standalone tasks. The default full-document planner list plan.yaml --parents form is also supported. Filters select original parts before summarizing; partial selections carry a visible count. Mixed fields and partial timing are indicated. Source tasks remain authoritative for budgets, readiness and dependencies. Positional fields, configured list presentation and --ignore-config support the flag. It is independent of export.layout.multipart and is rejected for non-task list kinds.

Task funding values in list output include a dollar prefix (for example, $50K) and appear green when colors are enabled. This also applies to selected funding fields and configured task lists. Closed and unfunded task blocks retain their gray and muted amber colors.

Activity funding, including nested execution/plan activity summaries, also uses dollar-prefixed green amounts in list output.

Nested plan organization and export placement

fields plan now emits execution with description, activities, tasks, milestones, and deliverables, plus resourcing with project dependencies, stakeholders, users, and risks. fields execution and fields resourcing print the corresponding containers. Flat authored plans remain readable; fields cannot be defined in both locations, even if empty. Included collection files remain lists: move their include directives beneath the appropriate container. Word import writes nested plans. Merge/split preserve the input’s organization. show also accepts paths such as execution.tasks.label and resourcing.dependencies.id; existing object view and field names remain available.

export.structure specifies section order and execution/resourcing groups independently of export.elements content selection. The execution group’s introductory description precedes its listed children; activities places activity definitions. Empty/excluded sections produce no parent heading. Word/PDF use subordinate outline levels. SVG/PowerPoint follow narrative placement; their existing formats do not render the Word funding table. Without structure, existing elements declaration order remains supported. See Export Options for the placement syntax and per-standard overrides.

Export selection containers

export.elements now uses the same execution/resourcing containers as plan YAML, with the generated funding table at resourcing.task_table. Nested child declaration order supplies the default export placement. structure remains an optional placement override. Flat field selections remain compatible; a field cannot be specified in both locations, even when disabled or empty. Task and definition instructions work within the nested children. Execution spacing inherits to its selected children; resourcing spacing inherits to its selected prose/definition children, with explicit child overrides taking precedence. The task table remains independent. fields config prints the canonical nested configuration. Existing configured terminal list selections keep their own object scopes and are unchanged.

Word/PDF final table pagination

Exports keep Word’s required empty paragraph after a final task table compact, avoiding a blank last page caused by normal body paragraph formatting. This applies to portrait and landscape tables, including per-standard layouts and custom body font sizes.

Priority Schema Migration

migrate-priorities PATH [--config PATH] [--write] explicitly migrates YAML plans or a directory of YAML plans. By default it reports changes without writing. With --write, it backs up every changed file before saving. It renames the configuration vocabulary to task_priorities, moves former project assignments into task-list defaults, and changes export/list selections and the old project_priorities table column to task priority. Includes and comments are retained. Singleton lists become scalar IDs. Multiple IDs, legacy urgency values, and conflicting assignments require review before writing; unrelated older schema errors remain for review.

Editing a plan entry

edit ID [task_file] [--kind KIND] [--owner TASK_ID]

planner edit config opens the complete active general configuration. planner config edit is an equivalent alias. --config PATH selects an alternate file. This form does not require or load a plan, and can repair an invalid configuration. It uses the same editor, retry/cancel behavior, atomic saves and numbered backups described below, validating the complete configuration before saving. Comments and formatting are preserved as edited. A missing implicit default is initialized; an explicitly selected missing file is an error. Symlinks are preserved by editing their resolved target, with backups beside that target. Concurrent changes to the target or a change in the selected path’s resolution prevent saving. To select a plan entry literally named config, supply its plan file or --kind. --owner does not apply to configuration editing.

Open one authored mapping as a temporary YAML buffer using TUXFAN_PLANNER_EDITOR. For example:

export TUXFAN_PLANNER_EDITOR='vim'
planner edit BUILD_WING plan.yaml
planner edit RELEASE_GATE --kind milestone
planner edit 'aircraft/design#42' plan.yaml --kind workitem --owner BUILD_WING

The file defaults to TUXFAN_PLANNER_DATAFILE; relative input paths honor TUXFAN_PLANNER_DATA_DIRECTORY. Editor commands accept quoted paths and arguments without a shell. A GUI editor must wait until editing finishes (for example, code --wait). If that variable is unset or empty, planner uses EDITOR. Set at least one of these variables to a usable editor command. Editor failures retain the buffer and leave plan files alone.

Kinds are task, activity, milestone, deliverable, dependency, project-risk, and workitem. Matching uses exact, case-sensitive IDs. Multipart parents and parts are editable; use an expanded ID for a part. The buffer retains authored inheritance rather than inserting effective defaults. IDs shared across kinds require --kind; repeated work-item references require their authored task’s ID in --owner. ID-less prose, defaults and private task risks have no ID selector. The selected ID must remain unchanged; use rename to change an ID and its semantic references.

Planner validates the complete plan with the replacement in memory before saving, using the active configuration and normal warning/error rules. Unrelated validation errors also prevent saving. Invalid buffers can be reopened or cancelled; cancellation, validation failure, editor failure and write failure retain the edited buffer at the printed path. An unchanged buffer exits without saving or creating a backup.

A successful edit replaces only the selected authored entry, in its original included file when applicable, with a numbered backup and atomic save. Other source text remains unchanged. Concurrent changes to any loaded plan source prevent saving. YAML anchors, aliases and merge mappings within the selected entry are unsupported. Python plans support uniquely located literal dictionaries, converted back from the YAML editing buffer; computed entries are rejected before launching the editor. Normal Python plan loading executes the plan, including when validating a replacement.

Renaming IDs and references

rename OLD_ID NEW_ID [task_file] [--kind KIND] [--owner TASK_ID] [--write]

Preview a validated ID rename and its semantic reference updates. --write applies the prepared changes with numbered backups without prompting. Otherwise, when both input and output are terminals, the preview ends with Apply this rename? [y/N]:. Only y or yes (case-insensitive) writes; Enter, other responses and end-of-input decline. Ctrl-C cancels with exit status 130. With redirected/noninteractive input or output, it remains a preview unless --write is supplied. Omit the file to use TUXFAN_PLANNER_DATAFILE; relative inputs honor TUXFAN_PLANNER_DATA_DIRECTORY. --config selects normal validation vocabularies. No editor or editor environment variable is required.

planner rename BUILD_WING DESIGN_WING plan.yaml
planner rename BUILD_WING DESIGN_WING plan.yaml --write
planner rename RELEASE_GATE FINAL_GATE --kind milestone --write
planner rename PARENT_A C plan.yaml --kind task --write

Selection follows edit: exact case-sensitive IDs across task, activity, milestone, deliverable, dependency, project-risk and workitem kinds. Use --kind for overlapping namespaces and --owner for repeated work-item references. Work-item renaming changes the selected authored reference only; no server object or other owner’s reference is changed.

Reference updates

Renamed kind

Authored reference fields updated

Task or multipart part

Task dependencies, including sibling aliases and expanded IDs

Activity

Task activity

Milestone

Task milestones

Deliverable

Task deliverables and milestone deliverables

Project dependency

Task dependencies

Project risk

Project dependency risks

Work item

Selected owner’s work-item ID; there are no inbound plan references

A parent rename updates the parent’s alias and every expanded part ID. Parts authored with an explicit parent prefix are updated too. For a part, NEW_ID can be local or expanded; its local/prefixed authoring style is retained. Collisions are checked in the corresponding namespace, and full-plan validation checks cross-namespace constraints. The resolved dependency graph must retain the same relationships after applying the ID substitutions; ambiguous alias capture is rejected rather than silently redirecting edges.

Scope is the loaded plan and recursive includes. Other independent plans and configuration vocabulary IDs are not searched. Scalar source edits preserve surrounding formatting, comments, and quoting. Prose and labels containing old IDs remain literal. Affected YAML anchors, aliases or merged fields and computed Python entries/references must first be made explicit; literal Python IDs/references are supported without rewriting other code. Unchanged IDs exit without backups or prompts. An unconfirmed preview writes no plan source or backup files. Sources are checked again after confirmation so changes made while the prompt is open prevent saving.

Before saving, planner validates all replacement sources together and checks every input snapshot for concurrent changes. Each file is saved atomically with a numbered backup. A handled write failure restores already written files when they still contain the prepared replacement. A concurrent change prevents rollback from overwriting that file; errors identify manual recovery needs and retained backups. A forced termination can also require recovery from backups: there is no filesystem-wide atomic transaction across files.

Adding entries

add TYPE [task_file] [--parent TASK_ID] [--owner TASK_ID] [--destination PATH]

Open a YAML mapping template in TUXFAN_PLANNER_EDITOR or, if unset/empty, EDITOR. GUI editors need a wait option. TYPE is task, activity, milestone, deliverable, dependency, project-risk, or workitem. Templates use the same schema and active vocabulary examples as fields; optional task risk/work-item examples are commented out. For example:

planner add task plan.yaml
planner add milestone plan.yaml --destination milestones.yaml
planner add task plan.yaml --parent BUILD_WING
planner add workitem plan.yaml --owner BUILD_WING

--parent requires an existing multipart parent; nested parts are not supported. Part templates retain inheritance and include missing required fields when needed. Work items require --owner. Adding to a part with inherited references creates an override retaining the existing references. Duplicate IDs in the selected namespace are rejected. The editor buffer must contain exactly one mapping. An unchanged template cancels; invalid additions can be reopened or cancelled. Editor, validation or save failures retain the buffer at its printed recovery path. Valid entries save on editor exit, following full-plan validation; no additional confirmation is needed.

Composite plans offer a numbered destination menu scoped to the selected collection and owner. Choices may include the root plan, included lists, single-entry includes (converted into lists), or creation of a new included YAML file. --destination selects an existing compatible file or a new filename without the menu. Relative destinations use the root plan directory. New filenames require an existing directory and a .yaml or .yml suffix; existing unrelated files and input sources cannot be overwritten. A noninteractive/redirected composite addition requires an explicit destination. Empty input cancels destination selection. Raw task-list plans accept tasks only; adding other definition types requires a mapping plan.

New files and their include directives are validated together in memory before publication. New-file creation is exclusive, while changed existing files receive numbered backups. Handled save failures roll back created files and restore written files when they still match the prepared changes. Source changes during editor use prevent saving. Source text outside the affected collection/member is retained, as are includes, comments and collection order. Literal Python collections and mappings are supported; computed collections must be made explicit. Addition can repair a missing definition, provided the resulting complete plan passes validation. Existing dependency bindings cannot be silently redirected by a new multipart alias.

Removing entries

remove ID [task_file] [--kind KIND] [--owner TASK_ID] [--remove-references] [--write]

Preview removal of an exact ID, using the same kind/owner disambiguation as edit and rename. An existing valid plan is required for relationship analysis. Incoming references block removal by default and are listed with their owners. --remove-references clears them without removing the owner tasks or other definitions:

planner remove BUILD_WING plan.yaml
planner remove BUILD_WING plan.yaml --remove-references
planner remove RELEASE_GATE --kind milestone --remove-references --write
planner remove 'aircraft/design#42' --kind workitem --owner BUILD_WING --write

Cleanup includes incoming task dependency edges, task activity assignments, task milestone references, task/milestone deliverable references, and project dependency risk references. Outgoing fields disappear with the removed entry. Cleanup is not cascading task deletion. Normal validation warnings, including unproduced required outputs, remain visible before confirmation.

Parent removal includes its parts and references to their expanded IDs. Removing the last part is rejected: remove the parent instead. When a part is removed, parent-alias dependencies continue to require surviving parts. An inherited work-item removal for one part creates a local override; sibling references remain unchanged. Shared owner collections are isolated when needed to avoid changing other owners or dependency bindings.

In a terminal, a validated preview prompts Apply this removal? [y/N]:; only y or yes confirms. Enter/EOF decline and Ctrl-C cancels with status 130. --write bypasses confirmation. Noninteractive or redirected input/output remains preview-only without --write. Sources are rechecked after confirmation and before each write. Saves retain numbered backups, are atomic per file, and roll back handled failures as with rename.

Removing the last member of an included list retains an empty [] file and its include. Removing a single-mapping include detaches its directive without deleting the included file. No source files are deleted automatically. Python collections must be literal; affected YAML anchors/aliases and merged collection containers must first be made explicit. Both commands use the normal default file, data directory and --config settings. Scope is this plan and recursive includes, not other independent plans or configuration IDs.

Text width

The general configuration’s top-level max_width setting controls shared terminal and source-formatting widths (default 80, integer minimum 40). This includes terminal rules/prose, funding totals, help, discovery output and newly folded YAML source. planner format uses it for Python line length. Authored literal YAML values and export layout dimensions retain their existing behavior. See General Configuration for scope, exceptions and help fallback.

Staff Funding

list tasks FILE funding shows resolved annual totals, type amounts and staff calculations, including available FTE, assigned percentage and annual rate. The complete terminal document includes the same breakdown. Configuration labor_costing: annual keeps allocations independent of task duration; duration prorates by fiscal-year schedule overlap. rates_file selects the annual rate/staff catalog.

split --funding equal accepts coarse parent budgets; typed parent funding requires --funding parts to preserve type/staff allocations. See Funding and Staff Costs for examples and calculation rules.

Summary Markdown

Word/PDF export preserves summary line breaks and blank lines while retaining emphasis across lines, including quoted italics and bullet lists. Use YAML |/|- for explicit line breaks, or >/>- to fold source wrapping into paragraphs. Quotes inside literal blocks need no backslash escaping. Word import retains the exported italic formatting.

Coded Staff Allocations

list tasks FILE funding includes each selected staff allocation’s code in brackets. Staff catalogs and task labor entries accept optional code text; use it when the same staff ID has multiple coded allocations. Codes match exactly after trimming. Each person/code pair has its own available FTE and rate. See Funding and Staff Costs for selection and compatibility rules.

Rates files may group code allocations under one staff entry using a codes list. Each child has id and optional fte/rate; a shared parent rate is inherited. Existing flat coded entries remain supported. Task labor syntax continues to use id, code, and percent.

Task Cost

list tasks FILE cost and list FILE cost display derived costs by funding type and an overall total. Displayed costs round to whole K (halves up), after summing exact amounts; funding output and calculations keep their precision. Coarse funding is unclassified. The field also appears in default task/full-document output and list-detail. Configured lists opt in with list.elements.tasks.cost: true or an ordered cost instruction. It is output-only and cannot be authored on tasks or used as an export field.

List commands show Incomplete when rates are unavailable or required labor duration inputs are absent, retaining any known subtotal. Affected funding and actual/potential totals also remain incomplete. Invalid input/references still error, and validate, exports and authoring retain strict funding resolution. See Funding and Staff Costs for completeness and shared-parent behavior.

Labor funding code selection

list tasks FILE code displays the effective task funding code. Labor entries inherit a task’s code or its linked activity’s code; an individual labor entry can override that default. Funding detail displays the resolved code. See Funding and Staff Costs for YAML examples and clearing/inheritance rules.

Funding range shorthand

Typed funding accepts fiscal_range in place of a fiscal-year key to repeat an entry across the plan’s declared fiscal years. validate checks the resolved annual entries; list funding/cost fields and exports use those same values. Explicit-year entries override the default for that funding type and year. See Funding and Staff Costs for staff and amount examples.

Shared task funding

validate resolves typed funding covered_by references after loading all tasks, checks matching type/year/staff allocations and enforces optional share limits. list funding/cost fields display coverage separately from direct money; funding totals count the source budget once. Share percentages apply to source allocations, independently of receiving-task duration.

rename updates coverage references. remove blocks incoming coverage references unless --remove-references explicitly drops affected allocations. Merge/split retain and rewrite references when the source owner is unambiguous. See Funding and Staff Costs for syntax and import/export behavior.

Funding limited to task dates

Typed funding range uses the task’s inclusive start/end or start/expected span. fiscal_range continues to use the plan’s declared fiscal years. Explicit year entries override either default; one type cannot specify both. validate and authoring/export commands require sufficient explicit timing and reject range on ongoing tasks. list and list-detail can show missing-date ranges as incomplete, retaining known explicit-year amounts in funding/cost and annual totals. See Funding and Staff Costs for examples and costing rules.

Offline documentation

planner docs opens the HTML guide included with a pip installation in the default browser. Pages, styles, search and assets are installed together and work offline. planner docs --path prints the absolute index.html path without opening a browser, which is useful on remote terminals. Browser launch failure returns status 1 and reports the existing guide location.

These commands run independently of plan/configuration loading, including when an explicit configuration path is supplied. planner docs --help and planner help docs provide the same usage help. All three shell completions include the command and its --path option. Sphinx and Furo are build tools; normal installed use does not require them or website hosting.

In an editable checkout, build the guide first with:

python -m sphinx -b html docs docs/_build/html

The command recognizes that build and the standard CMake HTML output location. A checkout without a build reports the build command; an installed package with missing HTML reports that the package should be reinstalled.

Rates code validation

When a rates catalog is loaded for staff funding, its flat staff code and grouped codes[].id values must match XXXX_XXXX_XXXX (four uppercase ASCII letters/digits per group). Invalid codes report their rates-file location. Use underscores for dotted business codes; there is no automatic conversion. The fictional examples use codes such as DEMO_CORE_0000. Uncoded staff entries remain supported. See Funding and Staff Costs for rates and allocation examples.

Child funding shares

Multipart children may use share without covered_by to attribute the funded parent’s type/staff allocation. range, fiscal_range and explicit fiscal years use the same rules. validate permits explicit child-to-parent coverage and checks combined child/external share limits. Cost output shows explicit child attribution; --parents and annual financial totals retain the authoritative parent’s budget once. Ordinary inheritance is unchanged. See Funding and Staff Costs for syntax, source-code selection and renaming behavior.