CLI Reference

Kida ships eight subcommands:check, render, fmt, components, readme, extract, manifest, and diff. All are available through the kida entry point or python -m kida.

kida <command> [options]

Contract Status

The public CLI contract is the set of subcommands and flags documented here. Output text can become clearer, but machine-readable JSON shapes for components --json, readme --json, and manifestshould only change deliberately with docs and changelog updates when behavior changes.

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:

Flags:

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 --lint-fragile-paths

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

--validate-calls diagnostics use stable K-CMP-*codes:

components/page.html:12: K-CMP-001: Call to 'card' — missing required: title
components/page.html:18: K-CMP-002: type: card() param 'count' expects int, got str ('many')

kida render

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

kida render <template> [flags]

Positional argument:

Flags:

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:

Flags:

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

kida components

List all{% def %}components across templates in a directory. Useful for auditing component libraries and generating documentation.

kida components <template_dir> [flags]

Positional argument:

Flags:

Examples

List all components:

kida components templates/

Filter by name:

kida components templates/ --filter card

Machine-readable output:

kida components templates/ --json

Output format

Human-readable output groups by template file:

components/card.html
  def card(title: str, variant: str = ...)
    slots: (default), actions

components/nav.html
  def nav_link(href: str, label: str)

2 component(s) found.

JSON output produces an array of objects withname, template, lineno, params, slots, has_default_slot, depends_on, vararg, and kwarg fields. Each param includesname, annotation, has_default, and required.

kida manifest

Render templates with capture instrumentation and emit a render manifest as JSON. Frameworks can use this to track rendered block fragments and context keys.

kida manifest <template_dir> [flags]

Positional argument:

Flags:

kida diff

Compare two render manifests and report added, removed, and changed fragment content hashes.

kida diff <old_manifest> <new_manifest>

Positional arguments:

kida readme

Auto-generate a README from project metadata. Detects project structure frompyproject.toml, filesystem, and git, then renders a styled markdown README using Kida's own template engine.

kida readme [root] [flags]

Positional argument:

Flags:

Examples

Generate a README for the current project:

kida readme

Write to a file with a specific preset:

kida readme -o README.md --preset library

Override detected values:

kida readme --set description="A fast template engine" --set license=MIT

Inspect detected metadata:

kida readme --json

Use a custom template:

kida readme --template .github/readme.kida -o README.md

Presets

Python API

from kida.readme import detect_project, render_readme

# Auto-detect metadata
ctx = detect_project(root_path, depth=2)

# Render with a preset
md = render_readme(root_path, preset="library")

# Render with custom template and overrides
md = render_readme(
    root_path,
    template=Path("custom.kida"),
    context={"description": "Override"},
)

kida extract

Extract translatable messages from templates into a.pot(PO Template) file for internationalization workflows.

kida extract <template_dir> [flags]

Positional argument:

Flags:

Examples

Extract messages to stdout:

kida extract templates/

Write to a .potfile:

kida extract templates/ -o messages.pot

Scan only .html and .kidafiles:

kida extract templates/ --ext .html --ext .kida

Exit Codes

See Also

• Configuration Reference — environment and loader options
• Filters Reference — built-in filters
• API Reference — Python API forEnvironment, FileSystemLoader, and templates