Skip to content

CLI API Reference

The CLI is the process entry point and routing layer. It registers the current command surface, global options, and command dispatch. Domain logic lives below the CLI.

Current command groups:

  • discovery and planning transport commands
  • execution and full-pipeline orchestration commands
  • plugin inspection and validation commands
  • auxiliary docs and completion commands

dita_package_processor.cli

Unified command-line interface for dita_package_processor.

This module defines the root CLI entry point, global options, and subcommand dispatch. Subcommands are registered in dedicated modules.

Global concerns handled here
  • argument normalization
  • logging configuration
  • machine-readable output flags
  • implicit pipeline execution
  • docs and shell completion helpers
Design principles
  • argparse owns parsing
  • no manual flag handling
  • subcommands contain all behavior
  • this file is routing + orchestration only

build_parser()

Build and return the root argument parser.

Returns

argparse.ArgumentParser Configured CLI parser.

main(argv=None)

CLI entry point.

Behavior
  • --help/--version handled by argparse directly
  • implicit 'run' only when no command is supplied

dita_package_processor.cli_discover

Discovery CLI subcommand.

Runs discovery-only analysis over a DITA package directory and emits:

  • A human-readable summary (default)
  • Optional JSON discovery report (via --output or --json)
  • Optional invariant validation feedback

This command:

  • Does NOT transform content
  • Does NOT mutate files
  • Does NOT infer intent

It is a strict observational interface over the discovery subsystem. All results are deterministic, auditable, and schema-aligned.

register_discover(subparsers)

Register the discover subcommand.

Parameters:

Name Type Description Default
subparsers Any

Root argparse subparser registry.

 required

run_discover(args)

Execute discovery scanning and emit outputs.

Parameters:

Name Type Description Default
args Namespace

Parsed CLI arguments.

 required

Returns:

Type Description
int

Exit code.

dita_package_processor.cli_normalize

cli_normalize.py

Discovery → PlanningInput contract normalization CLI.

This command converts a raw discovery.json file into a validated planning_input.json contract.

Strict transport layer only.

Flow

file → normalize_discovery_report() → write

Responsibilities
  • Read discovery.json
  • Validate + normalize into PlanningInput
  • Write planning_input.json
Non-Responsibilities
  • No planning
  • No execution
  • No inference
  • No mutation of discovery content
  • No schema edits

All semantic logic belongs to: planning.contracts.discovery_to_planning

This module only performs IO and delegation.

register_normalize(subparsers)

Register the normalize subcommand.

Parameters

subparsers : Any argparse subparser collection.

Notes

This command only performs contract normalization. It does not plan or execute.

run_normalize(args)

Execute normalization workflow.

Strict pipeline:

discovery.json → PlanningInput → planning_input.json
Parameters

args : argparse.Namespace Parsed CLI arguments.

Returns

int Exit code:

- 0 → success
- 2 → setup or contract failure
Behavior
  • Fails fast on malformed JSON
  • Fails fast on contract violations
  • Never mutates discovery input

dita_package_processor.cli_plan

cli_plan.py

Planning CLI interface.

Thin controller only.

Flow

read → validate contract → plan → validate → write

Responsibilities
  • Read planning_input.json
  • Hydrate PlanningInput contract
  • Invoke Planner
  • Validate produced plan
  • Write plan.json
Non-Responsibilities
  • No discovery parsing
  • No normalization
  • No schema mutation
  • No inference
  • No business logic

This file is strictly a transport/controller layer.

register_plan(subparsers)

Register the plan subcommand.

Parameters

subparsers : Any argparse subparser collection.

run_plan(args)

Execute planning workflow.

Strict transport pipeline:

file → PlanningInput → planner → file
Parameters

args : argparse.Namespace Parsed CLI arguments.

Returns

int 0 success 1 planning failure 2 setup/contract failure

dita_package_processor.cli_execute

Execution CLI subcommand.

Executes a validated plan and produces an ExecutionReport.

Supports: --plan PATH required --output PATH required (execution target root) --report PATH optional --json optional

Design rules

CLI is dumb glue only.

It: - loads plan - mkdirs output - calls executor - writes report

It does NOT: - use Pipeline - perform discovery - perform planning - perform materialization - invent layers - mutate implicitly

run_execute(args)

Execute a validated plan.

Responsibilities

CLI is glue only. It must:

  1. Validate inputs
  2. Load + normalize plan
  3. Create output directory
  4. Select executor
  5. Execute
  6. Emit report

It must NOT: - mutate planning logic - perform discovery - guess paths

Returns

int 0 success 1 execution failure 2 configuration / validation failure

dita_package_processor.cli_run

Pipeline orchestration CLI command.

This module implements the run subcommand, which represents the full DITA Package Processor pipeline:

discover → plan → materialization → execute

Design rules:

  • Dry-run is the default and safest mode
  • Filesystem mutation is only allowed when --apply is provided
  • This command performs real orchestration
  • No planning, discovery, or execution logic lives here
  • The ExecutionReport is a first-class artifact

register_run(subparsers)

Register the run subcommand.

Parameters:

Name Type Description Default
subparsers _SubParsersAction

Root argparse subparser registry.

 required

run_pipeline(args)

Execute the full discovery → planning → materialization → execution pipeline.

This function is a strict orchestration boundary: - no discovery logic - no planning logic - no materialization logic - no execution logic

It validates user intent, wires the pipeline, and normalizes failures.

Parameters:

Name Type Description Default
args Namespace

Parsed CLI arguments.

 required

Returns:

Type Description
int

Process exit code.

dita_package_processor.cli_plugin

Plugin management CLI subcommand.

Provides commands for inspecting and validating the plugin stack:

dita_package_processor plugin list
    List all loaded plugins with their contributed patterns and handlers.

dita_package_processor plugin info <name>
    Print detailed information about a specific plugin.

dita_package_processor plugin validate <path>
    Validate a plugin from a local directory (imports directly from path).

These commands do not require a DITA package and do not mutate files.

register_plugin(subparsers)

Register the plugin subcommand group.