TerraTidy

<div align="center"> <picture> <img src="assets/brand.png" alt="TerraTidy" width="400" style="max-width: 100%; height: auto;"> </picture>

<b>A comprehensive quality platform for Terraform and Terragrunt</b>

</div>

Overview

TerraTidy is a single-binary quality platform for Terraform and Terragrunt that provides:

• Formatting -- Format .tf and .hcl files using the HCL formatter
• Style Checking -- Custom style rules for layout, ordering, and conventions
• Linting -- 11 built-in AST rules plus optional TFLint integration for provider-specific checks
• Policy Enforcement -- OPA policy checks for compliance

Key Features

• Single Binary -- No external dependencies for core functionality
• Library-first Architecture -- Uses Go libraries (hclwrite, OPA SDK) directly instead of shelling out
• Extensible -- Custom rules in Go, YAML, or Bash
• Modular Config -- Split large configs into organized files with glob imports
• Auto-fix -- Automatically fix formatting and style issues
• Multiple Output Formats -- Text, table, JSON, SARIF, HTML, JUnit, Markdown, GitHub Actions annotations
• Multi-platform -- Linux, macOS, Windows (amd64 and arm64)

Installation

Homebrew (macOS/Linux)

brew tap santosr2/tap https://github.com/santosr2/TerraTidy
brew install santosr2/tap/terratidy

Download Binary

Download the latest release for your platform from GitHub Releases.

Docker

docker pull ghcr.io/santosr2/terratidy:latest

# Pin to a specific version in CI
docker pull ghcr.io/santosr2/terratidy:v0.2.0-alpha.3

docker run --rm -v $(pwd):/app ghcr.io/santosr2/terratidy check

From Source

go install github.com/santosr2/TerraTidy/cmd/terratidy@latest

Quick Start

1. Initialize Configuration

cd your-terraform-project
terratidy init --interactive

This creates a .terratidy.yaml configuration file with recommended settings.

2. Run Checks

terratidy check

Example output (sequential mode, the default):

Checking 3 files...

1. Checking formatting...
   Found 1 issue(s)

2. Checking style...
   Found 2 issue(s)

3. Running linter...
   Found 1 issue(s)

4. Running policy checks...
   Found 0 issue(s)

✗ modules/networking/main.tf:0:0: File needs formatting (fmt.needs-formatting)
⚠ modules/networking/main.tf:12:1: Missing blank line between blocks (style.blank-line-between-blocks)
⚠ modules/networking/variables.tf:5:1: Missing blank line between blocks (style.blank-line-between-blocks)
⚠ modules/networking/main.tf:8:1: resource name 'public-subnet' should use snake_case (lint.terraform-naming-convention)
---
Summary: 4 total issue(s)

  Errors:   1
  Warnings: 3

Run individual commands for details:
  terratidy fmt --check
  terratidy style
  terratidy lint
  terratidy policy

With --parallel (-p), the output is more compact:

Checking 3 files...

Running checks in parallel mode...
  fmt: 1 issue(s)
  style: 2 issue(s)
  lint: 1 issue(s)

✗ modules/networking/main.tf:0:0: File needs formatting (fmt.needs-formatting)
⚠ modules/networking/main.tf:12:1: Missing blank line between blocks (style.blank-line-between-blocks)
⚠ modules/networking/variables.tf:5:1: Missing blank line between blocks (style.blank-line-between-blocks)
⚠ modules/networking/main.tf:8:1: resource name 'public-subnet' should use snake_case (lint.terraform-naming-convention)
---
Summary: 4 total issue(s)

  Errors:   1
  Warnings: 3

Run individual commands for details:
  terratidy fmt --check
  terratidy style
  terratidy lint
  terratidy policy

3. Auto-fix Issues

terratidy fix

Commands

| Command | Description | |------------------------|-------------------------------------------| | terratidy check | Run all checks (recommended for CI) | | terratidy fix | Auto-fix all fixable issues | | terratidy fmt | Format files | | terratidy style | Check/fix style issues | | terratidy lint | Run linting | | terratidy policy | Run policy checks | | terratidy init | Initialize configuration | | terratidy dev | Development mode with file watching | | terratidy lsp | Start the Language Server Protocol server | | terratidy init-rule | Initialize a new custom rule | | terratidy test-rule | Test a specific rule | | terratidy plugins | Plugin management commands | | terratidy config | Configuration management commands | | terratidy rules list | List available rules | | terratidy rules docs | Generate markdown documentation | | terratidy version | Show version info |

Global Flags

These flags apply to all commands:

| Flag | Description | | -------------------------- | ------------------------------------------------------------------------------------ | | --config | Path to config file (default: .terratidy.yaml) | | --profile | Configuration profile to use | | --format | Output format: text, table, json, json-compact, sarif, html, junit, markdown, github | | --changed | Only check files changed in git | | --paths | Specific paths to check | | --severity-threshold | Minimum severity to fail: info, warning, error | | --color | Enable colored output (default: true) |

Check Command Flags

These flags are specific to terratidy check:

| Flag | Description | | -------------------- | ---------------------------- | | --parallel / -p | Run engines in parallel | | --skip-fmt | Skip formatting checks | | --skip-style | Skip style checks | | --skip-lint | Skip linting checks | | --skip-policy | Skip policy checks |

Configuration

Simple Configuration

# .terratidy.yaml
version: 1

engines:
  fmt: { enabled: true }
  style: { enabled: true }
  lint: { enabled: true }
  policy: { enabled: false }

severity_threshold: warning

Modular Configuration

For larger projects, split configuration into organized files:

# .terratidy.yaml
version: 1

imports:
  - .terratidy/rules/*.yaml
  - .terratidy/profiles/default.yaml

severity_threshold: warning

See the Configuration Guide for details.

Integrations

| Method | When | Best For | | -------------- | -------------------- | --------------------------------- | | CLI | Manual runs | Local development, scripting | | Pre-commit | On git commit | Catching issues before push | | GitHub Actions | On PR/push | CI/CD quality gates | | LSP / VS Code | Real-time in editor | Instant feedback while coding | | Docker | Isolated environments| CI pipelines without Go installed |

Pre-commit Hook

Add to .pre-commit-config.yaml:

repos:
  - repo: https://github.com/santosr2/TerraTidy
    rev: v0.2.0-alpha.3
    hooks:
      - id: terratidy-check

Available hook IDs: terratidy-fmt, terratidy-fmt-check, terratidy-style, terratidy-style-fix, terratidy-lint, terratidy-check, terratidy-fix, terratidy-policy.

GitHub Action

- name: Run TerraTidy
  uses: santosr2/terratidy@v0
  with:
    format: sarif
    parallel: true
    github-token: ${{ secrets.GITHUB_TOKEN }}

Pin to a specific release for reproducible builds: santosr2/terratidy@v0.2.0-alpha.3

Available inputs: version, config, profile, format, parallel, working-directory, skip-fmt, skip-style, skip-lint, skip-policy, fail-on-error, fail-on-warning, github-token.

VS Code Extension

The TerraTidy VS Code extension provides real-time diagnostics via LSP. See vscode/README.md for installation instructions.

Custom Rules

Create custom rules in three formats:

Go Plugin

package custom

func (r *EnforceTaggingRule) Check(ctx *sdk.Context,