evnx template — Command Reference

Generate configuration files from templates using .env variables, with support for flexible substitution syntax and powerful filter transformations.

Command signature

evnx template --input <TEMPLATE> --output <OUTPUT> [--env <ENV_FILE>] [--verbose]

Required arguments

Optional options

Gitignore protection

Generated config files contain real values injected from .env and must never be committed. After writing the output file, evnx template can automatically add it to .gitignore.

Behaviour by flag and context

The default (--no-gitignore absent) is safe in both contexts: interactive users get a one-keystroke prompt, CI pipelines get a visible warning without a blocking prompt.

What gets written

Entries are grouped under a labelled section so they are easy to identify:

# ── evnx generated ─────────────────────────────────────────
# Files generated by `evnx template` may contain secrets — do not commit.
config.toml
k8s/configmap.yaml

Running evnx template again with the same --output detects the existing entry and prints "already in .gitignore" without adding a duplicate.

Git root detection

evnx walks ancestor directories from the current working directory looking for a .git entry (directory or file, so worktrees are supported). The .gitignore is located at that root. If no .git ancestor is found, the check is skipped with a warning when --gitignore is explicitly set.

The entry written to .gitignore is always relative to the git root, regardless of where you run the command from.

Variable substitution syntax

The template engine supports three styles for referencing variables from your .env file:

Filter transformations

Apply transformations to variable values using the pipe (|) operator within double braces:

{{VAR|filter}}

Supported filters

JSON filter example

The |json filter properly escapes values for embedding in JSON structures:

# If VALUE = hello "world"
# Template:  "desc": {{VALUE|json}}
# Output:    "desc": "hello \"world\""

Basic usage examples

Generate a config file from template

# Simple substitution: replace ${VAR} patterns with .env values
evnx template --input config.yaml.template --output config.yaml

Use a custom environment file

# Generate production config using .env.production
evnx template -i deploy.yaml.tpl -o deploy.yaml --env .env.production

Enable verbose output for debugging

# See detailed progress and variable loading info
evnx template -i template.json -o output.json --verbose

Generate multiple configs in a script

#!/bin/bash
# Generate configs for multiple environments — auto-protect output files in CI
for env in dev staging prod; do
  evnx template \
    --input config.yaml.template \
    --output "config.${env}.yaml" \
    --env ".env.${env}" \
    --gitignore \
    --verbose
done

Opt out of gitignore management

# You manage .gitignore externally (e.g. via a generator or monorepo tooling)
evnx template \
  --input config.yaml.template \
  --output config.yaml \
  --env .env.production \
  --no-gitignore

When to use evnx template

Exit codes

Troubleshooting

"Failed to parse environment file" error

✗ Failed to parse environment file: .env.production

Solution: Validate your .env file syntax or run evnx validate --env .env.production to check for issues. Ensure the file uses valid KEY=VALUE syntax:

• ›One variable per line
• ›No spaces around = (KEY=value, not KEY = value)
• ›Quote values with spaces: KEY="value with spaces"
• ›Use # for comments

"Variable 'X' referenced but not defined" warning

⚠️ Variable 'MISSING_VAR' referenced in template but not defined in .env
ℹ️ Tip: Define 1 undefined variable to avoid runtime issues

Solution: Add the missing variable to your .env file, or use the |default:value filter to provide a fallback:

{{MISSING_VAR|default:fallback_value}}

Filter transformation errors

✗ Failed to process template substitutions
Caused by: Variable 'PORT' value 'not-a-number' is not a valid integer for |int filter

Solution: Ensure the variable value in your .env file is a valid integer. If the variable might be absent or malformed, provide a validated default in .env rather than relying on the template:

# In .env — validate and set a safe default before templating
PORT=${PORT:-8000}

Or use the |default filter on a separate variable:

# Only use |default — filters cannot be chained
{{PORT|default:8000}}

"Not a git repository" warning with --gitignore

⚠️  Not a git repository — cannot update .gitignore

Cause: evnx walks ancestor directories looking for .git/ and reached the filesystem root without finding one. This happens when running outside a git repository or from a temp directory in CI.

Solutions:

• ›Run the command from within your repository root
• ›If you are not using git, add --no-gitignore to silence the warning
• ›If using git worktrees, the .git file (not directory) is also detected correctly

Output file already in .gitignore

✓ 'config.toml' is already in .gitignore

This is correct behavior — idempotent. evnx checks for an exact line match before writing. Running evnx template multiple times with the same --output and --gitignore will never produce duplicate entries.

JSON filter output has unexpected quotes

# Template: key={{VALUE|json}}
# Output:   key="hello \"world\""

This is correct behavior. The |json filter returns a properly quoted JSON string literal, including the surrounding double quotes. Use it when embedding values directly inside JSON structures:

{
  "description": {{DESCRIPTION|json}}
}

If DESCRIPTION = hello "world", the output will be:

{
  "description": "hello \"world\""
}

Environment variables

See also

• ›Template Syntax Guide — Deep dive into substitution patterns and filter reference
• ›Gitignore Protection — How evnx detects git roots, writes entries, and handles edge cases
• ›Configuration Management — Strategies for managing configs across environments
• ›CI/CD Integration — Automating config generation in pipelines
• ›Security Best Practices — Safely handling sensitive values in templates
• ›evnx sync — Keep .env and .env.example synchronized before templating