jinjitsu 0.1.1

Jinja CLI with all features

jinjitsu

Minimal Jinja CLI for rendering templates from files or stdin with variables, config files, and Python modules. Fast, predictable way to render Jinja2 templates from the terminal.

Installation • Quick Start • CLI • Examples • Troubleshooting • Contributing • License

Quick Start

• Hello world:

  $ echo "Hello {{ name }}" | jinjitsu --stdin -D name=World
  Hello World
  

• Render a template with includes from a different directory

  docs/README.j2.md:

  # Dynamically rendered README
  
  ```ts
  {% include 'code.ts' %}
  ```
  

  examples/code.ts:

  export const greeting = "Hello, User";
  

  Now, rendering it with jinjitsu and adding examples as a --searchpath will produce the following result:

  $ jinjitsu docs/README.j2.md -s examples/
  # Dynamically rendered README
  
  ```ts
  export const greeting = "Hello, User";
  ```
  

  Or render it directly to a file by redirecting > the output or using the -o option:

  # Like so
  $ jinjitsu docs/README.j2.md -s examples/ -o README.md
  
  # Or like so
  $ jinjitsu docs/README.j2.md -s examples/ > README.md
  

• Autoescape HTML and feed template as a Heredoc (<<EOF)

  $ jinjitsu --stdin -D name='<World>' --autoescape on <<EOF        
  Hello {{ name }}
  EOF
  Hello &lt;World&gt;
  

CLI

Usage: jinjitsu [OPTIONS] [TEMPLATE]

Render a Jinja template.

Source (choose one)
  TEMPLATE                  Path to a template file.
  --stdin                   Read template from STDIN (heredoc/pipe).

Variables
  -D, --var KEY=VALUE       Set a string variable (repeatable). Highest precedence.
  --vars FILE               Load variables from FILE [json|yaml|toml|ini] (repeatable).
  -m, --module PATH         Import Python file; its top‑level names become variables (repeatable).

Template search paths
  --searchpath PATH         Add a directory for includes/imports (repeatable).

Jinja behavior
  --autoescape {smart,on,off}   Default smart (by extension).
  --autoescape-exts EXT,EXT     Override smart extensions (default: html,htm,xml,xhtml).
  --undefined {strict,default,debug,chain}   Missing variables policy (default: strict).
  --trim-blocks, --lstrip-blocks, --keep-trailing-newline
  --newline-sequence {\n,\r\n,\r}

Output and diagnostics
  -o, --output PATH         Write output to PATH (use - for stdout).
  --traceback               Show full Python tracebacks on errors.

Installation

Run using uv without needing to install anything:

uvx jinjitsu

Or install as a system-wide tool:

# Using uv
uv tool install jinjitsu

# Using pipx
pipx install jinjitsu

Of course, you can also install as a package in the current virtual environment:

./.venv/bin/activate && pip install jinjitsu

Examples

Let's consider an example with dynamically generated release notes. We want to render a template that uses a function from a Python module, includes a reusable sub-template, and uses variables from a vars file and the CLI.

# First, let's create a Python module with a two functions and a private variable
$ cat > extras.py <<'PY'
from datetime import datetime

def greet(name: str) -> str:
    """Greet someone."""
    return f"Greetings, {name}!"

def today() -> str:
    """Return today's date."""
    return datetime.now().strftime('%Y-%m-%d')

_private_variable = "visible"
PY

# Then, we create a vars.json file with additional variables
$ echo '{ "changelog": "CHANGELOG.md" }' > vars.json

# Let's also create a reusable template in the "shared" directory
$ mkdir -p shared && echo 'Release type: {{ type }}' > shared/type.j2

# Finally, let's define the main template
$ cat > deployment_summary.j2 <<'J2'
Deployment summary {{ today() }}

* {% include 'type.j2' %}
* Changelog: {{ changelog }}
* Status: {{ _private_variable }}
J2

# Now, render the template with jinjitsu
$ jinjitsu deployment_summary.j2 \
  --module extras.py \
  --vars vars.json \
  -D type=PROD \
  --searchpath shared

Expected output:

Deployment summary 2023-04-10

* Release type: PROD
* Changelog: CHANGELOG.md
* Status: visible

Configuration & Notes

• Variable precedence:
  • Later sources override earlier ones
  • -D/--var flags override --vars files, which override -m/--modules.
• Include/import search order:
  • template’s directory;
  • for --stdin, falls back to the current working directory;
  • always adds all provided -s/--searchpath directories to the above.

Troubleshooting

• “YAML file not supported” or similar

  • Install a YAML parser: pip install PyYAML (or ruamel.yaml).

• “Unsupported vars file type …”

  • Only .json, .yaml/.yml, .toml, .ini are supported.

• “Template not found” or includes fail

  • Check the path and add directories with --searchpath PATH.

• “UndefinedError” or missing variables

  • Default mode is strict. Provide values via -D/--var, --vars FILE, or --module; or use --undefined default.

• Newline/whitespace looks wrong

  • Try --trim-blocks, --lstrip-blocks, and set --newline-sequence. Use --keep-trailing-newline to preserve a single trailing newline.

• I need a Python traceback

  • Add --traceback for full tracebacks on errors.

Contributing

Pull requests and issues are welcome.

License

Apache 2.0. See LICENSE.