Skip to content

CLI.md

Latest commit

 

History

History
169 lines (129 loc) · 4.51 KB

CLI.md

File metadata and controls

169 lines (129 loc) · 4.51 KB

CLI Reference

Syntax

tmpltool [TEMPLATE] [OPTIONS]
cat template.txt | tmpltool [OPTIONS]

Arguments

  • [TEMPLATE] - Path to template file (optional, reads from stdin if omitted)

Options

  • -h, --help - Print help information and exit
  • -V, --version - Print version information and exit
  • -o, --output <FILE> - Output file path (prints to stdout if not specified)
  • --trust - Trust mode: Allow filesystem functions to access absolute paths and parent directories
    • WARNING: Only use with trusted templates. Disables security restrictions.
  • --validate <FORMAT> - Validate output format (json, yaml, or toml)
    • Validates the rendered output conforms to the specified format
    • Exits with error code 1 if validation fails
    • No output on success, error message only on validation failure
  • --ide <FORMAT> - Output function metadata for IDE integration (json, yaml, or toml)
    • Prints all available functions with descriptions, arguments, return types, and examples
    • Exits immediately after printing metadata (does not render templates)
    • Useful for building IDE plugins, autocomplete, and documentation generators
  • --env <FILE> - Load environment variables from .env file(s)
    • Can be specified multiple times: --env .env --env .env.local
    • Files are loaded in order; later files override variables from earlier ones
    • Supports standard .env format: KEY=value, comments (#), and quoted values

Input/Output Patterns

Input Output Command
File stdout tmpltool template.txt
File File tmpltool template.txt -o output.txt
stdin stdout cat template.txt | tmpltool
stdin File cat template.txt | tmpltool -o output.txt

Examples

# Get help
tmpltool --help

# Check version
tmpltool --version

# File to stdout
tmpltool template.txt

# File to file
tmpltool template.txt -o output.txt

# Stdin to stdout (pipe)
echo "Hello {{ get_env(name=\"USER\") }}!" | tmpltool

# With environment variables
DB_HOST=postgres tmpltool config.tmpltool -o config.txt

# Chaining with other tools
tmpltool config.json.tmpltool | jq .
cat k8s-deployment.yaml.tmpltool | tmpltool | kubectl apply -f -

# Trust mode for system files
tmpltool --trust system_info.tmpltool  # Can read /etc/passwd, etc.

# Validate JSON output
tmpltool config.json.tmpltool --validate json
# Exits with error if output is invalid JSON

# Validate YAML output
tmpltool k8s-deploy.yaml.tmpltool --validate yaml -o deployment.yaml

# Validate TOML output
tmpltool Cargo.toml.tmpltool --validate toml

# Load variables from .env file
tmpltool --env .env config.tmpltool

# Load from multiple env files (later files override earlier)
tmpltool --env .env --env .env.local config.tmpltool

# Combine with other options
tmpltool --env .env --env .env.production --validate json -o config.json config.tmpltool

Environment Files (.env)

The --env flag loads variables from .env files before template rendering. This is useful for:

  • Storing configuration separately from templates
  • Managing different environments (development, staging, production)
  • Avoiding environment variable pollution in your shell

.env File Format

# This is a comment
DATABASE_URL=postgres://localhost:5432/mydb
API_KEY=secret123

# Quoted values preserve spaces
APP_NAME="My Application"
DESCRIPTION='Single quotes work too'

# Empty values
EMPTY_VAR=

# Special characters in unquoted values
URL=https://example.com/path?key=value

Multiple Environment Files

Load multiple files to layer configurations:

# .env (base configuration)
APP_NAME=myapp
LOG_LEVEL=info
DATABASE_URL=postgres://localhost/dev

# .env.production (production overrides)
LOG_LEVEL=warn
DATABASE_URL=postgres://prod-server/prod

# Load both - production values override base
tmpltool --env .env --env .env.production app.config.tmpltool

Example Workflow

Template (config.tmpltool):

server:
  host: {{ get_env(name="SERVER_HOST", default="localhost") }}
  port: {{ get_env(name="SERVER_PORT", default="8080") }}
database:
  url: {{ get_env(name="DATABASE_URL") }}
logging:
  level: {{ get_env(name="LOG_LEVEL", default="info") }}

Environment file (.env):

SERVER_HOST=0.0.0.0
SERVER_PORT=3000
DATABASE_URL=postgres://db:5432/myapp
LOG_LEVEL=debug

Render:

tmpltool --env .env config.tmpltool -o config.yaml

Output (config.yaml):

server:
  host: 0.0.0.0
  port: 3000
database:
  url: postgres://db:5432/myapp
logging:
  level: debug