expand Command

Expand templates and data files into YAML output.

Syntax

koji-habitude expand [OPTIONS] DATA [DATA...]

Description

The expand command loads templates from specified locations, processes data files through template expansion, and outputs the final YAML content to stdout. This is useful for:

  • Previewing template expansion without connecting to Koji

  • Generating intermediate YAML for debugging

  • Validating template expansion logic

  • Creating static YAML from dynamic templates

  • Integration with other tools that consume YAML

Note that templates may be declared in the data files alongside objects. The --templates options provides a way to specify locations such that only templates are loaded from those locations, no other objects. This can be be useful for borrowing templates from other data sets, without also including the data itself.

The command performs:

  1. Load templates from --templates locations

  2. Load and process data files

  3. Expand templates using Jinja2

  4. Validate expanded objects (if --validate is used)

  5. Output final YAML to stdout

Note: This command does not connect to Koji and does not modify any remote state. It’s a purely local operation.

Options

DATA

One or more directories or files containing YAML object definitions. Required. Can be repeated multiple times.

--templates PATH, -t PATH

Location to find templates that are not available in DATA directories. Can be repeated multiple times.

--recursive, -r

Search template and data directories recursively for YAML files.

--validate

Validate the expanded templates and data files using Pydantic models. When enabled, outputs fully validated objects. When disabled (default), outputs raw expanded data.

--include-defaults, -d

Include default values in output. By default, default values are excluded. Only applies when --validate is used.

--no-comments

Do not include comments in the YAML output. Comments are included by default.

--select TYPE, -S TYPE

Filter results to only include objects of the specified type(s). Can be repeated multiple times to select multiple types.

Examples

Expand templates and data files:

koji-habitude expand data/

Expand with validation enabled:

koji-habitude expand --validate data/

Expand and only output tags and targets:

koji-habitude expand --select tag --select target data/

Expand with templates from multiple locations:

koji-habitude expand --templates templates/ --templates shared/ data/

Use Cases

  • Template Debugging: See exactly what templates expand to

  • Pre-Processing: Generate static YAML from dynamic templates

  • Validation: Use --validate to check template expansion correctness

  • Type Filtering: Extract specific object types using --select

  • Integration: Pipe output to other tools that consume YAML

Exit Codes

  • 0 - Success

  • 1 - Error (e.g., validation failure, missing templates)