Configuration¶

TerraTidy is configured using a .terratidy.yaml file in your project root.

Configuration File¶

Basic Structure¶

version: 1

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

severity_threshold: warning
fail_fast: false
parallel: true

Engine Configuration¶

Each engine can be enabled/disabled and configured:

engines:
  fmt:
    enabled: true

  style:
    enabled: true
    config:
      fix: false  # Auto-fix mode

  lint:
    enabled: true
    config:
      config_file: .tflint.hcl  # Path to TFLint config

  policy:
    enabled: true
    config:
      policy_dirs:
        - ./policies

# Rule overrides go here, NOT under engines.*.config
overrides:
  rules:
    style.block-label-case:
      enabled: true
      severity: warning

Configuration Precedence¶

Settings are resolved in this order (highest priority first):

CLI flags (--config, --profile, --severity-threshold, etc.)
Config file (.terratidy.yaml)
Defaults (fmt/style/lint enabled, policy disabled, severity=warning)

Environment Variables¶

Configuration values can use environment variables with three syntaxes:

Syntax	Behavior
`${VAR}`	Substitutes the value; empty string if unset
`${VAR:-default}`	Uses `default` if `VAR` is unset
`${VAR:?error}`	Required variable (empty string if unset)

engines:
  policy:
    config:
      # Simple variable
      api_key: ${API_KEY}

      # With default value
      region: ${AWS_REGION:-us-east-1}

      # Required variable
      account_id: ${AWS_ACCOUNT_ID:?must be set}

Select a profile via CLI flag:

terratidy check --profile ci  # Uses the "ci" profile

Profiles¶

Define different configuration profiles for different contexts:

profiles:
  ci:
    description: "CI/CD strict checks"
    engines:
      fmt: { enabled: true }
      style: { enabled: true }
      lint: { enabled: true }
      policy: { enabled: true }

  development:
    description: "Fast development checks"
    engines:
      fmt: { enabled: true }
      style: { enabled: true }
      lint: { enabled: false }
      policy: { enabled: false }

Use a profile:

terratidy check --profile ci

Profile Inheritance¶

Profiles can inherit from other profiles:

profiles:
  base:
    engines:
      fmt: { enabled: true }
      style: { enabled: true }

  strict:
    inherits: base
    engines:
      lint: { enabled: true }
      policy: { enabled: true }

Disabling Inherited Engines¶

Use disabled_engines to turn off engines from a parent profile:

profiles:
  minimal:
    inherits: base
    disabled_engines:
      - lint
      - policy

Rule Overrides¶

Override specific rule configurations:

overrides:
  rules:
    style.blank-line-between-blocks:
      enabled: false

    lint.terraform-required-version:
      severity: error
      config:
        min_version: "1.5.0"

Custom Rules¶

Define custom rules:

custom_rules:
  my-org.naming-convention:
    enabled: true
    severity: warning
    config:
      pattern: "^(dev|staging|prod)_.*"

Plugins¶

Enable and configure plugins:

plugins:
  enabled: true
  directories:
    - ~/.terratidy/plugins
    - ./plugins
  verify_integrity: true  # Verify plugin checksums (default: true)

Plugin Integrity Verification¶

When verify_integrity is enabled (default), TerraTidy verifies Go plugin checksums against a .terratidy-plugins.sha256 manifest file in each plugin directory.

Create the manifest using sha256sum:

cd ~/.terratidy/plugins
sha256sum *.so > .terratidy-plugins.sha256

The manifest format is compatible with sha256sum output:

e3b0c44298fc1c149afbf4c8996fb924...  myplugin.so
b94d27b9934d3e08a52e52d7da7dabfa...  anotherplugin.so

If verification fails or the manifest is missing, a warning is logged but the plugin still loads (warn-only mode). Set verify_integrity: false to disable verification entirely.

Configuration Imports¶

Split configuration across multiple files:

version: 1

imports:
  - ./config/base.yaml
  - ./config/rules/*.yaml

engines:
  # local overrides

Imported files can themselves contain imports, which are loaded recursively. Circular imports (e.g., a.yaml imports b.yaml which imports a.yaml) are detected and produce a clear error.

Full Example¶

version: 1

imports:
  - ./terratidy-rules.yaml

severity_threshold: warning
fail_fast: false
parallel: true

engines:
  fmt:
    enabled: true
  style:
    enabled: true
  lint:
    enabled: true
    config:
      config_file: .tflint.hcl
  policy:
    enabled: true
    config:
      policy_dirs:
        - ./policies

profiles:
  ci:
    description: "Strict CI checks"
    engines:
      fmt: { enabled: true }
      style: { enabled: true }
      lint: { enabled: true }
      policy: { enabled: true }

  dev:
    description: "Fast dev checks"
    engines:
      fmt: { enabled: true }
      style: { enabled: true }

# Rule overrides - enable/disable rules, change severity
overrides:
  rules:
    style.block-label-case:
      enabled: true
      severity: warning
    lint.terraform-required-providers:
      severity: error

plugins:
  enabled: true
  directories:
    - ~/.terratidy/plugins

Global Settings¶

fail_fast¶

When enabled, stops processing after the first engine that reports error-severity findings. Only triggers on error severity, not warnings or info. Only applies to sequential execution (not --parallel).

fail_fast: true  # Stop after first engine with errors

Cache¶

TerraTidy caches parsed HCL files to avoid redundant reads. The cache is managed automatically and rarely needs configuration.

Option	Type	Default	Description
`MaxAge`	duration	5m	Maximum age of cache entries
`MaxSize`	int	1000	Maximum number of entries (LRU)
`Disabled`	bool	false	Disable caching entirely

Cache is invalidated when a file's modification time changes.

Lint Engine¶

The lint engine provides 11 built-in AST rules and can optionally invoke TFLint as an external subprocess for provider-specific checks. Configure it under engines.lint.config:

engines:
  lint:
    enabled: true
    config:
      config_file: .tflint.hcl    # Path to TFLint config (optional)
      plugins:                     # TFLint plugins to enable (optional)
        - aws
        - terraform

Built-in rules work without TFLint. If TFLint is installed and configured, provider-specific rules are also available. TFLint is invoked as a subprocess, not embedded or linked.

File Discovery¶

Supported File Types¶

TerraTidy processes files with these extensions:

.tf - Terraform configuration files
.hcl - HCL configuration files
.tfvars - Terraform variable files

All three types are handled by all engines (fmt, style, lint, policy) and supported by the LSP, dev watch mode, and --changed flag.

Skipped Directories¶

These directories are automatically skipped during file discovery:

node_modules/ - npm dependencies
vendor/ - Go dependencies
.terraform/ - Terraform provider cache
.terragrunt-cache/ - Terragrunt cache
__pycache__/ - Python cache
Hidden directories (starting with .) except the current directory

Command Line Overrides¶

Configuration can be overridden via command line:

terratidy check \
  --config custom.yaml \
  --profile ci \
  --severity-threshold error \
  --format json