CLI Reference

Command-line tools for checking, rendering, and formatting Kida templates

3 min read 641 words

Kida ships three subcommands:check for validation, render for output, and fmt for formatting. All are available through the kida entry point or python -m kida.

kida <command> [options]

kida check

Parse all.htmltemplates under a directory. Reports syntax errors, loader resolution failures, and optional lint checks.

kida check <template_dir> [flags]

Positional argument:

Argument Description
template_dir Root directory passed toFileSystemLoader. All *.htmlfiles are scanned recursively.

Flags:

Flag Description
--strict Fail on bare{% end %} closers. Requires explicit {% endif %}, {% endblock %}, {% endcall %}, etc.
--validate-calls Validate macro call sites against{% def %}signatures. Reports unknown parameters, missing required parameters, and duplicates.
--a11y Check templates for accessibility issues (missingaltattributes, heading order, etc.).
--typed Type-check templates against{% template %}declarations.

Examples

Basic syntax check:

kida check templates/

Strict mode with call validation:

kida check templates/ --strict --validate-calls

Full lint pass (all checks enabled):

kida check templates/ --strict --validate-calls --a11y --typed

Output format

Errors and warnings print to stderr, one per line:

layouts/base.html: unexpected tag 'endblock'
partials/nav.html:12: strict: unified {% end %} closes 'if' — prefer {% endif %}
components/card.html:8: a11y/img-alt [WARNING]: <img> missing alt attribute

kida render

Render a single template to stdout. Supports HTML and terminal rendering modes.

kida render <template> [flags]

Positional argument:

Argument Description
template Path to the template file to render.

Flags:

Flag Default Description
--data FILE none JSON file providing template context variables.
--data-str JSON none Inline JSON string providing template context variables.
--mode {html,terminal} terminal Rendering mode.terminalenables ANSI styling and width-aware layout.
--width INT auto Override terminal width (terminal mode only).
--color {none,basic,256,truecolor} auto Override color depth (terminal mode only).
--stream off Progressive output: reveal template chunks with a brief delay.
--stream-delay SECONDS 0.02 Delay between stream chunks. Requires--stream.

Examples

Render with inline data:

kida render page.html --data-str '{"title": "Hello"}'

Render from a JSON file in HTML mode:

kida render page.html --data context.json --mode html

Terminal mode with explicit width and color:

kida render dashboard.html --width 120 --color 256

Streaming output:

kida render report.html --data stats.json --stream --stream-delay 0.05

kida fmt

Auto-format Kida template files. Accepts individual files or directories (scans for*.htmlrecursively).

kida fmt <paths...> [flags]

Positional argument:

Argument Description
paths One or more files or directories to format.

Flags:

Flag Default Description
--indent INT 2 Spaces per indentation level.
--check off Check formatting without writing changes. Exits1if any file would be reformatted.

Examples

Format all templates in a directory:

kida fmt templates/

Format specific files with 4-space indent:

kida fmt layouts/base.html partials/nav.html --indent 4

CI check (no writes, non-zero exit on drift):

kida fmt templates/ --check

Exit Codes

Code Meaning
0 Success. No errors or formatting drift.
1 One or more problems found (check), render failure, or formatting drift (fmt --check).
2 Invalid input: path not found, bad JSON data, or unknown command.

See Also