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 check --format json, components --json, readme --json, and manifest should 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')

Text output goes to stderr. JSON and SARIF go to stdout, so either machine format can be redirected without mixing in human progress text:

kida check templates/ --typed --a11y --format json > diagnostics.json
kida check templates/ --strict --format sarif > diagnostics.sarif

The JSON envelope is versioned by schema_versionand includes the resolved root, ordered diagnostics, severity summary, partialcollection status, andexit_code. Its published schema is schemas/diagnostics/v1/check.schema.json. Each diagnostic always includes its stable code, category, severity, message, path/range, optional suggestion and safe edit, related locations, confidence, notes, documentation URL, source snippet, and metadata. Kida source columns are zero-based in JSON; SARIF columns are converted to SARIF's one-based convention.

Machine-readable findings are deterministically ordered by validation phase, path, range, code, and message. Exact duplicates with the same code, path, range, and message are emitted once. A failed template does not stop the rest of the directory scan;partial: truerecords that at least one requested analysis could not be completed.

Diagnostic confidence describes the kind of evidence behind a finding:

• provenmeans parsing or static analysis established the finding.
• conservativemeans static analysis intentionally chose the safe warning when it could not rule a problem out.
• runtime-onlymeans the fact came from execution and cannot be claimed as a compile-time proof.
• unknownmeans the producer has not classified its evidence yet.

Exit status is0 when there are no findings, 1when any enabled check emits a finding, and2for an invalid invocation or template root. Severity labels do not change this existing check policy.

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