@formatr/cli

Command Line Interface for the formatr template library.

Installation

npm install -g @formatr/cli
# or
npm install --save-dev @formatr/cli

Quick Start

# Render a template
echo "Hello {name}!" | formatr render --data '{"name":"World"}'

# Validate templates
formatr validate ./templates --recursive

# Start the playground
formatr playground

Commands

formatr render

Render templates with provided data.

# Render from file with JSON data
formatr render template.fmt --data data.json --output result.txt

# Render from stdin
echo "Hello {name}!" | formatr render --data '{"name":"World"}'

# Render with YAML data
formatr render template.fmt --data config.yaml

# Render multiple templates
formatr render ./templates --data data.json --output-dir ./dist --recursive

# Watch mode
formatr render template.fmt --data data.json --watch

formatr validate

Validate template syntax and structure.

# Validate single template
formatr validate template.fmt

# Validate directory
formatr validate ./templates --recursive

# Validate with context (check placeholders exist)
formatr validate template.fmt --context data.json

# Strict mode (treat warnings as errors)
formatr validate template.fmt --strict

# Output as JSON for CI
formatr validate template.fmt --json

formatr analyze

Analyze template complexity and characteristics.

# Analyze single template
formatr analyze template.fmt

# Analyze with detailed metrics
formatr analyze template.fmt --detailed

# Compare multiple templates
formatr analyze template-v1.fmt template-v2.fmt --compare

# Output as JSON with threshold for CI
formatr analyze template.fmt --json --threshold complexity=10

formatr benchmark

Benchmark template rendering performance.

# Basic benchmark
formatr benchmark template.fmt --data data.json

# Multiple iterations
formatr benchmark template.fmt --data data.json --iterations 10000

# Compare implementations
formatr benchmark template-v1.fmt template-v2.fmt --data data.json

# Memory profiling
formatr benchmark template.fmt --data data.json --memory

# Generate HTML report
formatr benchmark template.fmt --data data.json --report benchmark.html

formatr report

Generate reports from templates and data.

# Generate HTML report
formatr report --template report.fmt --data results.json --format html

# Generate markdown report
formatr report --template report.fmt --data results.json --format markdown

# Batch report generation
formatr report --template report.fmt --data-dir ./data --output-dir ./reports

# Custom styles
formatr report --template report.fmt --data data.json --format html --style custom.css

formatr watch

Watch templates and data files for changes.

# Watch single template
formatr watch template.fmt --data data.json --output result.txt

# Watch directory
formatr watch ./templates --data-dir ./data --output-dir ./dist

# Watch with live reload server
formatr watch template.fmt --data data.json --serve --port 3000

# Watch with custom debounce
formatr watch template.fmt --data data.json --debounce 500

formatr init

Initialize a new formatr project.

# Interactive initialization
formatr init

# Initialize with template
formatr init my-project --template basic

# Initialize TypeScript project
formatr init my-project --template typescript

# Create config file only
formatr init --config-only

Available templates:

• basic - Basic formatr project
• typescript - TypeScript project with types
• advanced - Advanced project with examples
• documentation - Documentation project

formatr format

Format template files according to style guidelines.

# Format single file
formatr format template.fmt

# Format directory
formatr format ./templates --recursive

# Check only (don't modify)
formatr format template.fmt --check

# Format with specific style
formatr format template.fmt --style compact

formatr lint

Lint templates for best practices and potential issues.

# Lint single template
formatr lint template.fmt

# Lint directory
formatr lint ./templates --recursive

# Fix auto-fixable issues
formatr lint template.fmt --fix

# Output as JSON for CI
formatr lint template.fmt --json

formatr playground

Launch an interactive playground.

# Launch playground in browser
formatr playground

# Launch on custom port
formatr playground --port 8080

# Launch with initial template
formatr playground --template examples/basic.fmt

# Launch in CLI mode (REPL)
formatr playground --cli

Configuration

The CLI supports configuration files in the following order of precedence:

1. .formatrrc (JSON)
2. .formatrrc.json
3. .formatrrc.yaml / .formatrrc.yml
4. formatr.config.js / formatr.config.mjs / formatr.config.cjs

Example .formatrrc.json:

{
  "templateExtension": ".fmt",
  "outputDir": "./dist",
  "locale": "en-US",
  "lint": {
    "extends": "recommended",
    "rules": {
      "no-empty-placeholders": "error"
    }
  },
  "format": {
    "style": "expanded",
    "indentation": 2
  },
  "watch": {
    "debounce": 300,
    "extensions": [".fmt", ".json", ".yaml"]
  }
}

Exit Codes

The CLI uses standard exit codes for CI/CD integration:

• 0 - Success
• 1 - Command failure (e.g., validation errors, render errors)
• 2 - Invalid usage (e.g., missing required arguments)

Environment Variables

• NO_COLOR - Disable colored output
• FORCE_COLOR - Force colored output
• DEBUG - Enable debug logging

CI/CD Integration

GitHub Actions

steps:
  - name: Validate templates
    run: formatr validate ./templates --recursive --json > validation.json
    
  - name: Lint templates
    run: formatr lint ./templates --recursive --json > lint.json
    
  - name: Check complexity
    run: formatr analyze ./templates --json --threshold complexity=10

Pre-commit Hook

{
  "scripts": {
    "precommit": "formatr lint ./templates --recursive && formatr format ./templates --check"
  }
}

Troubleshooting

Colors not displaying

Try setting FORCE_COLOR=1 or ensure your terminal supports ANSI colors.

YAML support not working

Install the optional yaml package:

npm install yaml

Watch mode not working

Install the optional chokidar package:

npm install chokidar

Interactive mode not working

Install the optional inquirer package:

npm install inquirer

License

MIT