Command Line Interface¶
The package installs two console scripts:
plannerPrimary command.
tuxfan-plannerBackward-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:
Invocation |
Equivalent |
|---|---|
|
|
|
|
|
|
|
|
|
|
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.
Field-level diagnostics use the file and line that supplied the effective
value, including task defaults and fields inherited across YAML includes.
Funding warnings point to the defining funding entry.
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 and child prose is omitted. Categories combine all distinct child IDs
in authored part order; terminal views show their labels and IDs, narratives show
labels, and table cells list each table code on its own line using the column
alignment. Other mixed fields retain 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 remain independent; terminal lists select parent aggregation with
--parents. 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_DATA_FILE. 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_DATA_FILE. 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_DATA_FILE, 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-v6to overrideexport.standardand 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
Task IDs, multipart parent IDs and the expanded IDs of other tasks must be unique across the assembled plan. Legacy funding mappings and funding lists require numeric amounts and one entry per normalized fiscal year. An empty YAML file or an empty task list represents an empty plan.
Validate a YAML or Python plan file. Task
priorityandriskare optional for every status. Omitted priority is unassigned; omit risk or userisk: []for no risks. Supplied values retain validation. Successful output is limited toValidation: PASSand counts of activity groups in use, expanded tasks, milestone and deliverable definitions, declared activities, configured fiscal years, work item references, project dependency definitions, project and inline task risks, and emitted warnings. Activities use the same grouping aslistand exports; unused activities count only under the declared activity count. 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 theWarnings: Nstatistics 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 printsValidation: FAILand an error diagnostic to stderr, with exit status 1; success exits with status 0.PASSis green andFAILis red on compatible stdout terminals; redirected output,NO_COLOR, andTERM=dumbkeep the status plain.show [task_file] FIELDPrint 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 tagsorplanner 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, andplan.project. Scalar lists are flattened, including tags, dependencies, task milestone references, assignees, and deliverables. Structured containers (tasks, risk, workitems, funding, execution) are not selectable.milestonesselects 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:activitiesforactivity(the collection name used bylistand--only)activities.id,activities.labelandactivities.descriptionforexecution.activities.*tasks.risk.type,tasks.risk.level,tasks.risk.descriptionandtasks.risk.mitigationforrisk.*
risk.*(andtasks.risk.*) selects inline task risks;risks.*selects project risk definitions.fields TYPEplanner fields colorsprints every effective terminal color as a plain YAMLterminal.colorsmapping, 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, andactivity. Plural aliasestasks,workitems,project-risks,risks,dependencies,milestones,deliverables, andactivitiesare accepted, along withexecution.activities.riskis a private task risk;risksis 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 taskprints one task mapping. Place it undertasksas a list item with appropriate indentation. Other mapping fragments also need their containing key or list.planner fields plan > new-plan.yamlwrites a complete starter plan; replace example values before use.planner fields config > new-config.yamlwrites a complete configuration template from packaged defaults, including commented optional allowlists and export alternatives. It does not read or initialize the user configuration;--configis ignored for this template, even if it names an invalid or missing file. Other types use the active configuration for vocabulary examples. Tasksiteandbnrexamples honor configured allowlists.typeaccepts 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 FIELDPrint finite schema options, one per line, without loading a plan or consulting input environment variables. Exactly one field is required.
statusprints separate labeled groups explaining task statuses (including blocked and unfunded) and work item entry statuses. Task statuses are alphabetical withclosedlast; work item statuses are ordered open, closed.prioritylists configured task priority IDs in declaration order.levellists risk levels in severity order: low, medium, high, extreme.risk.typelists required risk types: technical, schedule, operational, external, performance.priorityandcategorylist configured IDs, labels, and descriptions.typelists the built-in task types: labor, contract, equipment, services, nonlabor.siteandbnrlist 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, anddeliverables.statusare 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; explicittable_entryvalues use cyan. Labels, descriptions and headings remain plain. Redirected output,NO_COLORandTERM=dumbdisable 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 optionaltable_entryfields. 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 colorslists terminal palette attributes, default/effective values, and colored hex values.--color auto|always|nevercontrols all avail colors. Configure overrides throughterminal.colors; see General Configuration. Standard ANSI default hex values are conventional equivalents because terminal themes can change their actual appearance. Useplanner show FILE FIELDfor values actually used in a plan. Unsupported fields, unknown fields, containers, missing fields, and multiple fields are usage errors (exit status 2). Use--helpto see all selectable field names.merge task_file TASK_ID TASK_ID... --id PARENT_ID --label LABEL --output output.yamlMerge 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 partspreserves effective part funding; inherited parent amounts can multiply totals.--funding equalreplaces part funding with equal shares of the parent budget among current parts in declaration order, assigning remainder cents to earlier recipients. When every part is complete or closed, all parts receive historical allocations and current totals stay zero. 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_DATA_FILE 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.
Sibling aliases apply to task dependencies. A funding covered_by ID names
a plan-wide owner, even when a sibling has the same short ID. Splitting a
parent preserves such external claims.
The report includes ID mappings, local dependency and funding reference 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
!includedirectives into a standalone YAML output file. Input defaults fromTUXFAN_PLANNER_DATA_FILE; output is required. Expansion preserves list order, defaults, and multipart definitions without requiring task-schema validation. Existing output can be replaced after successful expansion. Input files cannot be overwritten. Long prose is written as>blocks and lists as|blocks.--nestedmoves 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_DATA_FILE. 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 withpip install 'tuxfan-planner[format]'(orpip install -e '.[format]'in a checkout).YAML formatting follows nested
!includedirectives, 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.bakbackups 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’sformattarget 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 aspellorsudo apt install aspell aspell-en). The task file can default fromTUXFAN_PLANNER_DATA_FILE.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 atmax_widthcolumns (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,rto replace manually,ito ignore once,ato ignore for the session,dto add to the personal dictionary, orqto 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, and111thdo not trigger suffix warnings. Standalone suffixes, malformed ordinals such as22th, 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
.bakbackup (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.--personalselects an Aspell personal dictionary, overriding discovery; relative paths are resolved from the current directory. Otherwise, the nearest.planner-words.pwsin 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
enin the header;--lang en_USstill 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, andplanretain 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 --helpdocumentsKIND,task_file, andFIELDtogether under positional arguments.KINDenumerates all supported views, including compatibility views. The primary top-level elements matchexport.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.yamlorplanner 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 FILEretains the original compact task-only layout;list plan FILEretains its scoped metadata/relationship summary. With no kind, uselist FIELDto specialize output by any supported field identifier, such aslabel,status,assignees, ormitigation.FIELDis 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 asworkitemsshow their complete contents. Combine field selection with--onlyto filter tasks before displaying the requested information. Runplanner list tasks --helpfor supported scoped task fields, or see the field-selection reference below.The explicit
list tasksview 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 usinglabelor other field names. Without field names, each multipart group has an unnumbered parent heading displaying its label and ID, such asAirframe 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--onlyselects 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 asTask A.1: Baseline Design [BASELINE]beneath parent[AIRFRAME]; standalone tasks show their task ID. Expanded child IDs such asAIRFRAME_BASELINEremain the identifiers for dependencies and selectors; local part IDs are not selector aliases. Each heading is followed by its description, aNote: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: falsedisables 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 asFunding: $500K (FY27), $250K (FY28); dollar amounts are light green when color is enabled. AFunded Total:line at the bottom covers every configured fiscal year, including years with$0K, and reports amounts in thousands of dollars. Every part of anunfundedtask 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 aslabel (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-detailframes 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 thelabeloutline remain compact without structural rules. Color is automatic on compatible terminals;--colorandNO_COLORretain their existing behavior.labelalone 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 onlist. 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 autohonorsNO_COLOR,TERM=dumb, and stdout redirection;alwaysandneveroverride 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 (
Nonewhen 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, orCLOSEDstate. Ongoing task timing follows its funded fiscal years. Planning placeholders remainPLANNINGand displayUnscheduleduntilstartand eitherexpectedorendare supplied; unknown duration displays asUnspecified. Funding estimates do not create their schedule. Closed tasks require only id, label, description, category, and status; they also displayUnscheduleduntil both timing fields exist. Closed tasks use gray list styling; unfunded tasks use muted amber. Tasks without an activity appear underUnassignedin all displays. Top-levelprojectselects 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.docxwritesplans/proposal.v2.yaml. An explicit output filename overrides this default. Relative paths use the current directory; planner environment overrides are ignored. Input must be.docxand output.yamlor.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 DevelopmentbecomesENGINE_MODEL. Qualifiers remain, without a fixed word limit. Accents normalize to ASCII; labels without usable words fall back toTASK, and numeric labels receive aTASK_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 usesM1Q1of the first positive year; missing end usesM3Q4of 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. Recoveredunfundedstatus is retained when timing can be inferred. Missing status or unrecoverable required timing still becomesplanning. Ongoing timing remains funding-driven and actual completion dates are never inferred.When a selected export omitted a risk’s type, the importer uses
technicalas 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, andasc-v6output 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-v6is 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. Selectexport.standard: asc-v6when exporting the resulting draft. ASC v4 is recognized from export metadata or aProject 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 asa – 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, soi./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: textline is one entry with aFIXME_nID and label for you to rename. A numbered heading followed by bullets (1. Activity A — Workloads) prefixes each item’s description. Deliverables gettype: documentandstatus: 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 precedingFY27heading; 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
idfield 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]Document and Gantt exports replace the output path atomically after a successful write. If the final path component is a symbolic link, the exported file takes the place of that link. Its target keeps its contents.
Configuration
export.standardacceptslegacy(the unchanged default),asc-v4, orasc-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. Useexport.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 inplanner fields config.--standard legacy|asc-v4|asc-v6overridesexport.standardfor 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
startwith eitherexpected(inclusive months) orend(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 asA.1.1;format: full(the default) retainsTask ``. This changes presentation only, preserving IDs, numbering, and table output. See :doc:`export-options` and ``planner fields configfor the YAML syntax.Formatting instructions accept boolean
headingbeside a standalone field, as a grouped-line default, or on an individual line field. For example,- {description: null, heading: false}hidesDescription:. 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.docxand 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 withexport.layout.font_sizeand Word/PDF table text independently withexport.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.spacingtonormalfor reference-document paragraph spacing ortight(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.elementsin the general configuration selects fields through nested boolean mappings. Task narrative fields and table columns are selected independently.task_tablecontrols Word/PDF columns and totals.export.layout.task_tablecontrols presentation without enabling content. Risk and mitigation appear within task narratives, without a separate mitigation section. Narrative notes useelements.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 PATHselects a complete config.PowerPoint exports editable plan slides without requiring Office. Templates (
template.pptxortemplate.potx) are searched inTUXFAN_PLANNER_TEMPLATE_DIRECTORY, then the current directory; otherwise the built-in design is used.--template PATHselects a specific.pptx/.potxfile using a current-directory-relative or absolute path, bypassing template search. Missing or invalid files are errors. This option requires.pptxoutput. 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
.svgoutput path for a vector image or.pptxfor slides with editable PowerPoint shapes. As withexport, successful output replaces a destination symlink itself. PowerPoint output uses one or more slides, split by activity, row count, and long time ranges. Bars use the statedstartand an end month calculated from theexpectedduration, 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 asFY26throughFY27, or exact periods, such asM1Q1FY26throughM3Q2FY27. 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
.yamland.ymlplan input suggestions fromTUXFAN_PLANNER_DATA_DIRECTORYalongside 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
mergeandsplit. Output paths, export-options paths, personal dictionaries, option values, and fields after the input retain normal completion behavior. WhenTUXFAN_PLANNER_DATA_FILEsupplies the input forexport,export-gantt, orcomposite, their first filename is treated as an output, so data-directory candidates are not added there.completion installConfigure 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-editabletarget 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, calculatedactual_valueandpotential_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:descriptionandactivities, 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 plustasks(historically associated),direct_tasks,producer_tasks(required through outputs), andrequired_tasks(current direct/output requirements).deliverables: deliverable fields plusproducers,ready,required_by. Default output distinguishes actual, inferred, deferred, withdrawn, blocked, and awaiting-acceptance states.activities: section fields plustasks,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 plustasksand derivedtype(workitem/mr). Deduplicate by ID, merging owners for identical metadata. Conflicting metadata stays in owner-labeled variants.risks: risk fields plustasks. 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 asActivity B, or activity IDs.activities: activity IDs and labels; native taskactivityselects 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:
Source |
Fields |
|---|---|
Plan |
|
Task |
|
Work item |
|
Risk |
|
Deliverable definition |
|
Milestone definition |
|
Execution narrative |
|
Activity |
|
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_FILEOverrides configuration
rates_filefor 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_DATA_FILEDefault plan file. When set, basic commands can omit
task_fileand export commands andcompositecan 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_PAGEROptional 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/EDITOREditor executable and arguments for
addandedit. The planner-specific setting takes precedence; unset, empty or whitespace-only values fall back toEDITOR. 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 examplecode --wait.TUXFAN_PLANNER_DATA_DIRECTORYDirectory used for every relative plan filename, including the default from
TUXFAN_PLANNER_DATA_FILE. 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;!includepaths 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_DATA_FILE=tasks.yaml planner validate
This checkout provides fictional jet-airplane development fixtures under
data/; see Development Data.TUXFAN_PLANNER_TEMPLATE_DIRECTORYFirst directory searched for
template.pptxortemplate.potxby 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 affectexport-ganttor other formats.XDG_CONFIG_HOMEAbsolute 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_DATA_FILE=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.
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, complete and closed, with authoritative parent budgets once.
potential_value adds unfunded tasks and is never budget-colored; complete
and closed tasks remain excluded. 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 configopens the complete active general configuration.planner config editis an equivalent alias.--config PATHselects 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 namedconfig, supply its plan file or--kind.--ownerdoes 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_DATA_FILE; relative input paths honorTUXFAN_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 usesEDITOR. 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, andworkitem. 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; userenameto 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.
--writeapplies the prepared changes with numbered backups without prompting. Otherwise, when both input and output are terminals, the preview ends withApply this rename? [y/N]:. Onlyyoryes(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--writeis supplied. Omit the file to useTUXFAN_PLANNER_DATA_FILE; relative inputs honorTUXFAN_PLANNER_DATA_DIRECTORY.--configselects 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--kindfor overlapping namespaces and--ownerfor 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_EDITORor, if unset/empty,EDITOR. GUI editors need a wait option. TYPE istask,activity,milestone,deliverable,dependency,project-risk, orworkitem. Templates use the same schema and active vocabulary examples asfields; 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
--parentrequires 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.
--destinationselects 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.yamlor.ymlsuffix; 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
editandrename. An existing valid plan is required for relationship analysis. Incoming references block removal by default and are listed with their owners.--remove-referencesclears 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]:; onlyyoryesconfirms. Enter/EOF decline and Ctrl-C cancels with status 130.--writebypasses 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 withrename.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--configsettings. 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 Subscription¶
planner list staff [FILE] reports staff subscription by funding code:
planner list staff plan.yaml --year FY27
planner list staff plan.yaml --year FY27 --monthly --details
planner list staff plan.yaml --month M1Q1FY27 --staff STAFF_A
planner list staff plan.yaml --year FY27 --include-unfunded --format csv
The text view uses normal list section/item separators, colored identifiers,
field headings and the terminal.colors.subscription metric palette. Negative
balances and overcommitment use their own alert color. --color and
NO_COLOR follow normal list behavior; CSV stays plain.
It uses the active rates catalog, including unused staff/codes. Staff headings show the catalog label with the ID in square brackets, falling back to the bracketed ID, and sort by label. Each metric has its own labeled line. Subscribed measures assigned full-time effort. Available measures unused configured capacity, not a balance against an assumed 100% FTE. Code sections show Allocation, Subscribed and Available. Annual summaries use monthly averages and FTE-month ratios. Overcommitment periods remain visible. When duration costing lacks task dates, affected staff/code availability is unknown even for explicitly funded years. Both text and CSV retain known subscribed effort. Complete/closed work is excluded; unfunded work is separate proposed demand when requested. Parent budgets count once, and covered funding adds attribution without new demand.
--year and --month are mutually exclusive. The default is fiscal_current,
then plan fiscal years, then resolved allocation years. --staff and --code
may be repeated; --code uncoded selects fallback/uncoded entries. Filters hide
rows after full-plan calculation, and person totals include all codes. This
computed view uses these flags rather than positional fields or --only.
--format csv always outputs one staff/code/month row without terminal styling.
Use --details for consuming task IDs, shared parent members and coverage
attribution. Used effort is assigned effort, not expenditure or time worked;
other plans are outside its scope. See Funding and Staff Costs for formulas, unknown-input
handling, CSV columns and examples.
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 costs only months within the fiscal schedule overlap.
rates_file selects the rate/staff catalog. Rate amounts and staff assignments
accept effective-month histories (M1Q1FY27); FTE accepts scalars, whole fiscal
years, or monthly profiles (omitted months are zero). Funding detail groups months when FTE or
rates change. Invalid/missing histories and availability are errors. Combined
code FTE above 100% is rejected. Validation warns when monthly demand exceeds
a code allocation or the person capacity shown by list staff.
Shared parent budgets count once and coverage
does not add demand. Complete and closed tasks show excluded funding and do
not contribute to totals, cost or staff demand. Complete tasks bypass funding
validation; closed tasks retain it. A parent budget counts once if a current
part remains; historical-only coverage sources are unavailable.
See Funding and Staff Costs for the formats.
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 fiscal year, including covered dollar amounts with share/source context.
Staff IDs, source/share context and allocation codes appear on separate
indented lines beneath each fiscal-year amount. terminal.colors.funding_share
colors share/remainder explanations (default #FFFF99). Matching years collapse to one
annual amount with explicit exceptions; years are
never summed together. Grouping compares exact amounts before display rounding
to whole K (halves up). Standard funding/ID/heading colors and task status colors
apply. All funding output uses the same whole-K display; calculations retain exact
amounts. Unquantified
coverage shows Share unspecified. 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.
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.
Funding output rounding¶
All monetary funding output, including Totals, staff rates/details, coverage and project budgets, rounds to whole thousands with halves up. Each sum is computed from exact amounts and rounded only for its final display; individual rounded rows are never added to obtain a total. Word/PDF, SVG and PowerPoint use the same rule. See Funding and Staff Costs for examples and source/model precision guarantees.