Creating Templates

Your first template

Two files. That’s all you need.

hello/
  diecut.toml
  template/
    hello.txt.die

The config — diecut.toml:

[template]
name = "hello"

[variables.name]
type = "string"
prompt = "Your name"
default = "world"

The template file — template/hello.txt.die:

Hello, {{ name }}!

Run it:

diecut new ./hello -o output

Your name [world]: Alice

output/
  hello.txt

output/hello.txt

Hello, Alice!

That’s a template. You just made one.

The template/ directory contains your project files. Files ending in .die are rendered through the Tera template engine, then have the .die suffix stripped. Everything else is copied as-is.

Variable types

diecut supports six variable types.

string

Text input.

[variables.project_name]
type = "string"
prompt = "Project name"
default = "my-project"

bool

Yes or no.

[variables.use_ci]
type = "bool"
prompt = "Set up CI?"
default = true

int

Integer.

[variables.port]
type = "int"
prompt = "Default port"
default = 8080

float

Decimal number.

[variables.version]
type = "float"
prompt = "Initial version"
default = 0.1

select

Pick one from a list.

[variables.license]
type = "select"
prompt = "License"
choices = ["MIT", "Apache-2.0", "GPL-3.0"]
default = "MIT"

multiselect

Pick multiple from a list.

[variables.features]
type = "multiselect"
prompt = "Features to include"
choices = ["logging", "docker", "ci"]
default = ["logging"]

Conditional prompts

Use when to only ask a question when a previous answer makes it relevant.

[variables.use_ci]
type = "bool"
prompt = "Set up CI?"
default = true

[variables.ci_provider]
type = "select"
prompt = "CI provider"
choices = ["github-actions", "gitlab-ci"]
when = "use_ci"

ci_provider is only prompted when use_ci is true. The when field takes a bare Tera boolean expression — the same syntax used in {% if ... %} blocks.

Conditional files

Include or exclude entire files based on variable values.

[files]
conditional = [
    { pattern = ".github/**", when = "use_ci and ci_provider == 'github-actions'" },
    { pattern = ".gitlab-ci.yml", when = "use_ci and ci_provider == 'gitlab-ci'" },
]

Files matching the pattern are only included when the expression is true.

A real-world example from a Python template:

[files]
conditional = [
    { pattern = "src/cli.py*", when = "use_cli" },
]

This excludes src/cli.py.die when the user says no to the CLI entry point. The glob matches both the .die source and any related files.

Computed variables

Variables derived from other variables. Never prompted.

[variables.project_slug]
type = "string"
computed = "{{ project_name | slugify }}"

Computed variables are available in templates but never shown to the user. Use them for derived values like slugs, lowercase versions, or formatted strings.

A computed variable must not have a prompt field. If it does, diecut will report an error.

File handling

Excluding files

Keep files from the template out of the generated output:

[files]
exclude = ["*.pyc", "__pycache__/**", ".git/"]

Generally this won’t be useful if you’re making a template from git repository. However, if you’re making a template from a local directory, you might want to exclude files that you have already .gitignored.

Copying without rendering

Some files contain {{ }} or {% %} syntax that isn’t meant for Tera. Binary files, images, or files with their own template syntax.

[files]
copy_without_render = ["assets/**/*.png", "fonts/**"]

Files matching these patterns are copied verbatim. Tera syntax inside them is left alone.

Tera template basics

Five things you’ll actually use. See the Tera documentation for complete reference.

Variables

Insert a value:

{{ project_name }}

Conditionals

Include a block only when a condition is true:

{% if use_ci %}
ci: true
{% endif %}

Loops

Iterate over a list:

{% for feature in features %}
- {{ feature }}
{% endfor %}

Filters

Transform values inline:

{{ project_name | slugify }}
{{ name | upper }}
{{ description | truncate(length=50) }}

slugify turns “My Project” into “my-project”. upper uppercases. truncate cuts to length. See all built-in filters.

Comments

{# This won't appear in output #}

A complete example

A Cargo.toml.die from a Rust CLI template:

[package]
name = "{{ project_name }}"
version = "0.1.0"
edition = "{{ rust_edition }}"
description = "{{ description }}"
{% if author %}authors = ["{{ author }}"]
{% endif %}license = "{{ license }}"

Tera has much more. See the full Tera documentation for everything else.

Variable validation

Add a regex to constrain user input:

[variables.project_name]
type = "string"
prompt = "Project name"
validation = '^[a-z][a-z0-9_-]*$'
validation_message = "Must start with a letter. Only lowercase letters, numbers, hyphens, underscores."

If the input doesn’t match, the user is re-prompted with the validation message. No bad data gets through.