template

The kilm template command group provides tools for creating, managing, and using KiCad project templates. Templates allow you to standardize the starting structure for new projects.

Templates are stored within a templates directory inside a KiLM-managed library.

Subcommands

make

Creates a new project template from an existing KiCad project directory.

Usage

kilm template make <template_name> [project_path] [OPTIONS]

• <template_name>: Required. The name for the new template.
• [project_path]: The path to the KiCad project directory to use as the source. Defaults to the current directory.

Options

• --description TEXT: A description for the template.
• --use-case TEXT: Describe the intended use case for this template.
• --variable TEXT: Define a variable for the template (key=value pair). Can be used multiple times. These variables can be used within template filenames and file content using Jinja2 syntax (e.g., {{ author }}).
• --exclude TEXT: Glob pattern (like .gitignore) to exclude specific files or directories from the template. Can be used multiple times.
• --output-directory DIRECTORY: Specifies the directory where the templates/<template_name> structure will be created. Defaults to the templates directory within the KiLM library containing the current working directory. Example: kilm template make my-tmpl --output-directory /path/to/central/templates/dir
• --extends TEXT: Specify the name of a parent template. This template will inherit variables and potentially structure from the parent (feature details TBD).
• --non-interactive: Create the template without interactive prompts for configuration or variable detection. Default: False (interactive).
• --dry-run: Preview template creation without actually creating files.
• --force: Overwrite the template directory if it already exists. Default: False.
• --help: Show help message.

Behavior

1. Scans Project: Analyzes the source project directory.
2. Determines Output: Finds the target templates/ directory (either default or via --output-directory).
3. Creates Template Structure: Creates templates/<template_name>/.
4. Copies Files: Copies project files into templates/<template_name>/template/, respecting .gitignore and --exclude patterns.
5. Jinja Conversion: Renames files and replaces content using Jinja2 syntax based on detected project names and provided/detected variables (e.g., MyProject.kicad_pro becomes {{ project_filename }}.kicad_pro.jinja2).
6. Creates metadata.yaml: Generates a metadata.yaml file containing the template name, description, use case, detected/defined variables, and exclusions.
7. (Optional) Creates Hooks: Can set up pre/post-creation hook scripts (e.g., hooks/post_create.py).

Examples

Create template ‘basic-mcu’ from current directory (interactive):

cd /path/to/my-base-project
kilm template make basic-mcu

Create template from specific path with variables, excluding backups:

kilm template make advanced-fpga path/to/fpga-project \
    --description "Advanced FPGA project setup" \
    --variable "board_rev=1.2" \
    --variable "default_author=Jane Doe" \
    --exclude "*.bak" \
    --exclude "build/"

create

Creates a new KiCad project based on an existing template.

Usage

kilm template create <project_name_or_path> [output_path] [OPTIONS]

• <project_name_or_path>: Required. The name for the new KiCad project. If this contains path separators (e.g., path/to/MyNewBoard), the last component is used as the project name, and the preceding path is used as the default output_path.
• [output_path]: The directory where the new project will be created. If omitted, defaults to a directory named <project_name> in the current location, or the path derived from <project_name_or_path>.

Options

• --template TEXT: The name of the template to use. If not specified, KiLM will list available templates and prompt for selection.
• --set-var TEXT: Set a value for a template variable (key=value). Can be used multiple times. Overrides default values from metadata.yaml.
• --library TEXT: Specify the KiLM library containing the template (needed if multiple libraries have templates with the same name).
• --skip-hooks: Do not run any post-creation hook scripts defined in the template. Default: False (hooks run).
• --dry-run: Preview project creation without creating files.
• --help: Show help message.

Behavior

1. Finds Template: Locates the specified (or selected) template within the configured KiLM libraries.
2. Reads Metadata: Loads metadata.yaml to get variables and configuration.
3. Determines Variables: Uses default variables, potentially prompts interactively, and overrides with --set-var values.
4. Copies and Renders: Copies files from the template’s template/ directory to the output path.
5. Processes Jinja: Renders filenames and file content using Jinja2, substituting variables. The special variable project_filename is automatically set based on the project name.
6. (Optional) Runs Hooks: Executes the hooks/post_create.py script if it exists and --skip-hooks was not used.

Examples

Create project ‘MyNewBoard’ using ‘basic-mcu’ template (will prompt for template selection if ambiguous):

kilm template create MyNewBoard

Create project in specific dir, specifying template, setting variables:

kilm template create SensorModule projects/sensor --template advanced-fpga \
    --set-var board_rev=2.0 \
    --set-var default_author="My Name"

Create project using a path:

# Creates project 'MyBoard' inside './new_projects/'
kilm template create new_projects/MyBoard --template basic-mcu

list

Lists available project templates found in the configured KiLM libraries.

Usage

kilm template list [OPTIONS]

Options

• --library TEXT: List templates only from the specified KiLM library name.
• -v, --verbose: Show detailed information, including template description, use case, and variables.
• --json: Output the list in JSON format.
• --help: Show help message.

Examples

List all available templates:

kilm template list

List templates with details:

kilm template list --verbose

List templates from ‘my-main-lib’ in JSON:

kilm template list --library my-main-lib --json

Template Structure

Templates reside within a templates directory inside a library initialized with kilm init:

your-kilm-library/
├── kilm.yaml
├── symbols/
├── footprints/
└── templates/
    └── template-name/
        ├── metadata.yaml       # Template config (name, desc, vars)
        ├── hooks/
        │   └── post_create.py  # Optional post-creation script
        └── template/           # Files to be copied and rendered
            ├── {{ project_filename }}.kicad_pro.jinja2
            ├── {{ project_filename }}.kicad_sch.jinja2
            ├── {{ project_filename }}.kicad_pcb.jinja2
            ├── README.md.jinja2
            └── assets/
                └── logo-{{ company_name | lower }}.png.jinja2

• metadata.yaml: Defines template variables and descriptions.
• hooks/: Contains optional Python scripts to run after project creation.
• template/: Holds the project files.
  • Files ending in .jinja2 will have their content processed by Jinja.
  • Filenames containing {{ ... }} will be renamed based on variable values during project creation.
  • The special variable {{ project_filename }} is automatically derived from the project name provided to kilm template create and should be used for the main KiCad project files (.kicad_pro, .kicad_sch, .kicad_pcb).