templr

README

templr

Overview

templr is a powerful Go-based templating CLI inspired by Helm and Go's text/template package. Render templates from single files or entire directories with advanced features like linting, validation, and configuration management.

Perfect for:

• Generating Kubernetes manifests
• Creating configuration files
• Building documentation
• CI/CD pipelines
• Infrastructure as Code

Key Features

✨ Flexible Rendering - Single files, directories, or recursive tree walking 🔍 Lint Mode - Validate templates without rendering 🛡️ Guard Protection - Prevent accidental overwrites 📝 Configuration Files - Project and user-level .templr.yaml support 🎯 Strict Validation - Catch undefined variables and errors early 🔧 100+ Functions - Full Sprig function library included 📁 Enhanced .Files API - Read, parse (JSON/YAML), encode (Base64/Hex), and inspect files 🚀 CI/CD Ready - Exit codes, JSON output, GitHub Actions support

Quick Start

Installation

# macOS/Linux via Homebrew
brew tap kanopi/templr
brew install templr

# Or via curl
curl -fsSL https://raw.githubusercontent.com/kanopi/templr/main/get-templr.sh | bash

# Or via Docker (Alpine-based, only 18MB!)
docker pull kanopi/templr

Complete Installation Guide → | Docker Guide →

Basic Usage

# Render a single template
templr render -in template.tpl -data values.yaml -out output.txt

# Render entire directory tree
templr walk --src templates/ --dst output/

# Validate templates
templr lint --src templates/ -d values.yaml

Example

template.tpl:

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .app.name }}
  namespace: {{ .namespace }}
data:
  environment: {{ .environment }}
  version: {{ .app.version }}

values.yaml:

app:
  name: myapp
  version: "1.0.0"
namespace: production
environment: prod

Render:

templr render -in template.tpl -data values.yaml -out config.yaml

Documentation

📖 Guides

• Documentation Hub - Complete documentation index
• Templating Guide - Template syntax and features
• Configuration Files - .templr.yaml reference
• CLI Reference - All commands and flags
• Examples - Real-world use cases

🚀 Getting Started

• Installation Guide - Platform-specific installation
• Quick Start - Get up and running
• Basic Examples - Simple use cases

📚 Advanced Topics

• Team Workflows - Multi-developer setups
• CI/CD Integration - GitHub Actions, GitLab, CircleCI
• Multi-Environment - Dev/staging/prod configs

Common Commands

Rendering

# Single file
templr render -in template.tpl -data values.yaml -out output.txt

# Directory with helpers
templr dir --dir templates/ -in main.tpl -data values.yaml -out output.txt

# Walk entire tree
templr walk --src templates/ --dst output/ -data values.yaml

Validation

# Lint templates
templr lint --src templates/ -d values.yaml

# Strict validation (fail on warnings)
templr lint --src templates/ -d values.yaml --fail-on-warn

# JSON output for CI/CD
templr lint --src templates/ -d values.yaml --format json

Configuration

# Use project config (.templr.yaml)
templr lint --src templates/

# Use specific config
templr lint --config .templr.prod.yaml --src templates/

# User config is automatically loaded from ~/.config/templr/config.yaml

Complete CLI Reference →

Configuration Files

Create a .templr.yaml in your project root to set defaults and enforce policies:

# File handling
files:
  extensions: [tpl, yaml, md]
  default_values_file: ./values.yaml

# Linting rules
lint:
  fail_on_warn: true
  fail_on_undefined: true
  required_vars:
    - name
    - version
  disallow_functions:
    - env                # Block environment access
    - exec               # Block command execution

# Rendering defaults
render:
  inject_guard: true
  guard_string: "#templr generated"

Benefits:

• ✅ Shorter commands
• ✅ Version-controlled settings
• ✅ Team consistency
• ✅ Security policies

Complete Configuration Guide →

Use Cases

Kubernetes Manifests

# Generate and validate manifests
templr lint --src k8s/templates/ -d values.prod.yaml --fail-on-warn
templr walk --src k8s/templates/ --dst manifests/ -data values.prod.yaml
kubectl apply -f manifests/

Documentation Generation

# Generate docs from templates
templr walk --src docs/templates/ --dst docs/ --ext md -data api-spec.yaml

Configuration Management

# Multi-environment configs
templr render -in nginx.conf.tpl -data configs/dev.yaml -out /etc/nginx/nginx.conf
templr render -in nginx.conf.tpl -data configs/prod.yaml -out /etc/nginx/nginx.conf

More Examples →

CI/CD Integration

GitHub Actions

- name: Install templr
  run: curl -fsSL https://raw.githubusercontent.com/kanopi/templr/main/get-templr.sh | bash

- name: Validate templates
  run: templr lint --src templates/ -d values.yaml --format github-actions --fail-on-warn

- name: Render manifests
  run: templr walk --src templates/ --dst output/ -data values.yaml

Complete CI/CD Examples →

Exit Codes

templr uses specific exit codes for CI/CD integration:

Code	Description
0	Success
1	General error
2	Template error
3	Data error
4	Strict mode error
5	Guard skipped
6	Lint warnings (with --fail-on-warn)
7	Lint errors

Complete Exit Code Reference →

Contributing

We welcome contributions! To get started:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

See CONTRIBUTING.md for detailed guidelines.

Support

• Documentation: docs/
• Issues: GitHub Issues
• Discussions: GitHub Discussions

License

This project is licensed under the MIT License.

Acknowledgments

• Inspired by Helm and Go's text/template
• Uses Sprig for template functions
• Built with Cobra for CLI

---

📖 Read the Full Documentation | 🚀 View Examples | ⚙️ Configuration Guide

Documentation

Overview

Package main implements the templr CLI tool for rendering text templates with data and helpers.