validate

Usage

Recursively find HashiCorp Configuration Language (HCL) files and validate them.

Examples

Discover all HCL files in the current directory, and validate them.

terragrunt hcl validate

Flags

--filter

Filter configurations using a flexible query language

Experimental Feature

This feature is currently experimental and not yet complete. See the filter-flag experiment documentation for details on what is and isn’t supported.

Usage of the filter flag requires usage of the filter-flag experiment, like so:

terragrunt find --experiment filter-flag --filter 'foo'

Examples below will omit the --experiment filter-flag flag for brevity.

The --filter flag provides a sophisticated querying syntax for targeting specific units and stacks in Terragrunt commands.

Usage

terragrunt find --filter 'app*'
terragrunt list --filter './prod/** | type=unit'
terragrunt run --all --filter './prod/**' -- plan
terragrunt hcl fmt --filter './prod/**'
terragrunt hcl validate --filter 'type=unit'

Name-Based Filtering

Match configurations by their name using exact matches or glob patterns:

# Exact match
terragrunt find --filter app1

# Glob pattern
terragrunt find --filter 'app*'

Path-Based Filtering

Match configurations by their file system path:

# Relative paths with globs
terragrunt find --filter './envs/prod/**'

# Absolute paths
terragrunt find --filter '/absolute/path/to/envs/dev/apps/*'

Attribute-Based Filtering

Match configurations by their configuration attributes:

# Filter by type
terragrunt find --filter 'type=unit'
terragrunt find --filter 'type=stack'

# Filter by external dependency status
terragrunt find --filter 'external=false'

# Filter by files read
terragrunt find --filter 'reading=shared.hcl'
terragrunt find --filter 'reading=common/*.hcl' # Globs supported!
terragrunt find --filter 'reading=config/**' # Double-wildcard globs are required filtering on files nested in subdirectories.
terragrunt find --filter 'reading=config/vars.tfvars'

What does 'Reading' mean?

The reading attribute filters configurations based on which files they themselves read. This is useful for finding all infrastructure that could potentially be impacted by shared configuration, and is particularly useful when a commonly included configuration (like root.hcl) is updated.

See the mark_as_read function documentation for more information on how Terragrunt tracks files that are read during parsing.

Negation

Exclude configurations using the ! prefix:

# Exclude by name
terragrunt find --filter '!app1'

# Exclude by path
terragrunt find --filter '!./prod/**'

Intersection (Refinement)

Use the | operator to refine results:

# Find all units in prod directory
terragrunt find --filter './prod/** | type=unit'

# Chain multiple filters
terragrunt find --filter './dev/** | type=unit | !name=unit1'

Git-Based Filtering

Filter configurations based on changes between Git references. For the common use case of comparing the default branch with HEAD, you can use the --filter-affected flag as a convenient shorthand:

# Find components affected by changes between main and HEAD
terragrunt find --filter-affected

For more control, use Git-based filter expressions directly:

# Compare between two references
terragrunt find --filter '[main...HEAD]'

# Shorthand: compare reference to HEAD
terragrunt find --filter '[main]'

# Compare between specific commits
terragrunt find --filter '[abc123...def456]'

For more details and examples, see the Filters feature documentation.

Graph-Based Filtering

Filter configurations based on dependency relationships using graph traversal. Use ellipsis (...) to traverse the dependency graph and caret (^) to exclude the target from results.

Syntax variants:

• foo... - Include target and all dependencies (things it depends on)
• ...foo - Include target and all dependents (things that depend on it)
• ...foo... - Include target, dependencies, and dependents
• ^foo... - Include only dependencies (exclude target)
• ...^foo - Include only dependents (exclude target)
• ...^foo... - Include dependencies and dependents (exclude target)

# Find 'service' and everything it depends on
terragrunt find --filter 'service...'

# Find 'vpc' and everything that depends on it
terragrunt find --filter '...vpc'

# Find complete dependency graph for 'db'
terragrunt find --filter '...db...'

# Find dependencies of 'service' but exclude 'service' itself
terragrunt find --filter '^service...'

# Combine graph traversal with path filters (note the use of braces to escape the path)
terragrunt find --filter '{./apps/service}...'

# Combine graph traversal with attribute filters
terragrunt find --filter '...type=unit'

# Refine graph results with intersection
terragrunt find --filter 'service... | external=false'

Note

Graph expressions require dependency discovery to work correctly. When using graph expressions, Terragrunt automatically discovers dependency relationships between components. This may add some overhead compared to simple name or path filters.

For more detailed examples and explanations, see the Filters feature documentation.

Union (Multiple Filters)

Specify multiple --filter flags to combine results using OR logic:

# Find components named 'unit1' OR 'stack1'
terragrunt find --filter unit1 --filter stack1

The filters file

Instead of specifying filters on the command line, you can store filter queries in a file. By default, Terragrunt automatically reads filter queries from .terragrunt-filters in the working directory when the filter-flag experiment is enabled.

# Automatically reads .terragrunt-filters (no flag needed)
terragrunt find

# Use a custom filters file
terragrunt find --filters-file custom-filters.txt

# Disable automatic file reading
terragrunt find --no-filters-file

The filters file should contain one filter query per line. Empty lines and lines starting with # are ignored:

# Production environment filters
type=unit
./prod/**

# Exclude test units
!name=test-*

Supported Commands

Currently supported in:

• find
• list
• run
• hcl fmt
• hcl validate

Planned for future releases:

• dag graph

Learn More

For comprehensive examples and advanced usage patterns, see the Filters feature documentation.

Type: list(string)

--json

Output the result in JSON format.

When enabled, Terragrunt will output the validation results in JSON format, making it easier to parse and process programmatically.

Example:

terragrunt hcl validate --json

Type: bool

Environment Variables:

• TG_JSON

--show-config-path

Show a list of files with invalid configuration.

When enabled, Terragrunt will display the full paths of files that contain invalid HCL configurations. This is particularly useful when validating multiple files to quickly identify which files need attention.

Example:

terragrunt hcl validate --show-config-path

Type: bool

Environment Variables:

• TG_SHOW_CONFIG_PATH

--inputs

Validate that all variables a module requires are set.

When enabled, Terragrunt will validate that all variables a module (provisioned by a unit) requires are set.

Example:

terragrunt hcl validate --inputs

Type: bool

Environment Variables:

• TG_INPUTS

--strict

Throw an error if any inputs are set that are not defined in the module that a unit provisions.

When enabled, Terragrunt will throw an error if any inputs are set that are not defined in the module that a unit provisions.

Example:

terragrunt hcl validate --inputs --strict

Type: bool

Environment Variables:

• TG_STRICT

--queue-exclude-dir

Unix-style glob of directories to exclude from the queue of Units to run.

Alias for --filter

This flag is an alias for the --filter flag.

When using this flag, the equivalent filter expression is used instead.

e.g.

terragrunt run --all --queue-exclude-dir "prod/**" -- plan

is equivalent to:

terragrunt run --all --filter "!{./prod/**}" -- plan

Type: list(string)

Environment Variables:

• TG_QUEUE_EXCLUDE_DIR

--queue-exclude-external

Exclude external dependencies from the queue of Units to run.

Deprecated

This flag is deprecated and will be removed in a future version of Terragrunt. External dependencies are now excluded by default, making this flag unnecessary.

Use --filter flag with the expression {./**}... if you need to include external dependencies.

Type: bool

Environment Variables:

• TG_QUEUE_EXCLUDE_EXTERNAL

--queue-excludes-file

Path to a file with a list of directories that need to be excluded when running `run --all` commands.

Alias for --filters-file

This flag leverages the same underlying functionality as the --filters-file flag.

When using this flag, the .terragrunt-excludes file will be parsed, and converted to the equivalent filter expressions.

e.g.

excludes-file.txt

prod

terragrunt run --all --queue-excludes-file ./excludes-file.txt -- plan

is equivalent to:

filters-file.txt

!{./prod}

terragrunt run --all --filters-file ./filters-file.txt -- plan

Type: string

Default: .terragrunt-excludes

Environment Variables:

• TG_QUEUE_EXCLUDES_FILE

--queue-ignore-dag-order

Ignore DAG order for --all commands.

When enabled, Terragrunt will ignore the dependency order when running commands with --all. This means units will be executed in arbitrary order, which can be useful for read-only operations like plan.

Note that this can lead to errors if used with commands that modify state, as dependencies might be processed in the wrong order.

To learn more about how to use this flag, see the Stacks feature documentation.

Type: bool

Environment Variables:

• TG_QUEUE_IGNORE_DAG_ORDER

--queue-ignore-errors

Continue processing Units even if a dependency fails.

When enabled, Terragrunt will continue processing remaining units even if one fails. This can be useful when you want to see all potential errors in your configuration, rather than stopping at the first failure.

Note that this may lead to incomplete or inconsistent states if used with commands that modify infrastructure.

To learn more about how to use this flag, see the Stacks feature documentation.

Danger

Using --queue-ignore-errors can lead to inconsistent state if dependencies fail but dependent modules continue running.

Use this flag with caution, especially with apply or destroy commands.

For more fine-grained error handling, see the errors block in the HCL reference.

Type: bool

Environment Variables:

• TG_QUEUE_IGNORE_ERRORS

--queue-include-dir

Unix-style glob of directories to include in the queue of Units to run.

Alias for --filter

This flag is an alias for the --filter flag.

When using this flag, the equivalent filter expression is used instead.

e.g.

terragrunt run --all --queue-include-dir "prod/**" -- plan

is equivalent to:

terragrunt run --all --filter "{./prod/**}" -- plan

Type: list(string)

Environment Variables:

• TG_QUEUE_INCLUDE_DIR

--queue-include-external

Include external dependencies in the queue of Units to run.

Alias for --filter

This flag is an alias for the --filter flag.

When using this flag, the equivalent filter expression is used instead.

e.g.

terragrunt run --all --queue-include-external -- plan

is equivalent to:

terragrunt run --all --filter "{./**}..." -- plan

Type: bool

Environment Variables:

• TG_QUEUE_INCLUDE_EXTERNAL

--queue-include-units-reading

If flag is set, 'run --all' will only run the command against Terragrunt units that read the specified file via an HCL function or include.

Alias for --filter

This flag is an alias for the --filter flag.

When using this flag, the equivalent filter expression is used instead.

e.g.

terragrunt run --all --queue-include-units-reading shared.hcl -- plan

is equivalent to:

terragrunt run --all --filter 'reading=shared.hcl' -- plan

Type: string

Environment Variables:

• TG_QUEUE_INCLUDE_UNITS_READING

--queue-strict-include

Only process the directories matched by --queue-include-dir.

Deprecated

This flag is deprecated and will be removed in a future version of Terragrunt. Terragrunt performs strict inclusion by default, so this flag is no longer needed.

Type: bool

Environment Variables:

• TG_QUEUE_STRICT_INCLUDE