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'

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

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.

Specifies directories to exclude when running commands with all.

This flag can be specified multiple times to exclude multiple directories. When using the TG_QUEUE_EXCLUDE_DIR environment variable, specify the directories as a comma-separated list.

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

Note

When using --queue-exclude-dir, only the specified units are excluded, not their dependencies.

Dependencies of excluded units will still be run unless they are also explicitly excluded.

Note

Glob patterns must use Unix forward slashes / to separate directories, even on Windows machines.

Glob behavior for ** and **/* will change in a future version of Terragrunt.

See the double-star strict control for full details.

Type: list(string)

Environment Variables:

• TG_QUEUE_EXCLUDE_DIR

--queue-exclude-external

Exclude external dependencies from the queue of Units to run.

When enabled, Terragrunt will exclude external dependencies (dependencies outside the current working directory) from the queue when running commands with all.

Note that an external dependency is a dependency that is outside the current Terragrunt working directory and is not within any directories specified by queue-include-dir.

This flag is useful when you want to limit the scope of execution to only units within your current working directory structure.

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.

Units in these directories will be excluded during execution of the commands. If a relative path is specified, it should be relative from —working-dir. This will only exclude the module, not its dependencies.

This flag has been designed to integrate nicely with the hcl validate command, which can return a list of invalid files delimited by newlines when passed the --show-config-path flag. To integrate the two, you can run something like the following using bash process substitution:

terragrunt run --all plan --queue-excludes-file <(terragrunt hcl validate --show-config-path || true)

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.

Specifies directories to include when running commands with --all.

This flag can be specified multiple times to include multiple directories. When using the TG_QUEUE_INCLUDE_DIR environment variable, specify the directories as a comma-separated list.

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

Note

Glob patterns must use Unix forward slashes / to separate directories, even on Windows machines.

Glob behavior for ** and **/* will change in a future version of Terragrunt.

See the double-star strict control for full details.

Type: list(string)

Environment Variables:

• TG_QUEUE_INCLUDE_DIR

--queue-include-external

Include external dependencies in the queue of Units to run.

When enabled, Terragrunt will include external dependencies (dependencies discovered outside the current working directory) in the queue when running commands with --all or --graph.

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.

This flag works very similarly to the --queue-units-that-include flag, but instead of looking only for included configurations, it also looks for configurations that read a given file.

When passed in, the --all command will include all units (modules) that read a given file into the queue. This is useful when you want to trigger an update on all units that read or include a given file using HCL functions in their configurations.

Consider the following folder structure:

• Directoryreading-shared-hcl

  • terragrunt.hcl
• Directoryalso-reading-shared-hcl

  • terragrunt.hcl
• Directorynot-reading-shared-hcl

  • terragrunt.hcl
• shared.hcl

Suppose that reading-shared-hcl and also-reading-shared-hcl both read shared.hcl in their configurations, like so:

terragrunt.hcl

locals {
 shared = read_terragrunt_config(find_in_parent_folders("shared.hcl"))
}

If you run the command run --all init --queue-include-units-reading shared.hcl from the root folder, both reading-shared-hcl and also-reading-shared-hcl will be run; not not-reading-shared-hcl.

This is because the read_terragrunt_config HCL function has a special hook that allows Terragrunt to track that it has read the file shared.hcl. This hook is used by all native HCL functions that Terragrunt supports which read files.

Note, however, that there are certain scenarios where Terragrunt may not be able to track that a file has been read this way.

For example, you may be using a bash script to read a file via run_cmd, or reading the file via OpenTofu code. To support these use-cases, the mark_as_read function can be used to manually mark a file as read.

That would look something like this:

terragrunt.hcl

locals {
  filename = mark_as_read("file-read-by-tofu.txt")
}

inputs = {
  filename = local.filename
}

Caution

Due to how Terragrunt parses configurations during run --all, functions will only properly mark files as read if they are used in the locals block.

Reading a file directly in the inputs block will not mark the file as read, as the inputs block is not evaluated until after the queue has already been populated.

Type: string

Environment Variables:

• TG_QUEUE_INCLUDE_UNITS_READING

--queue-strict-include

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

When enabled, Terragrunt will only process directories that match the patterns specified by --queue-include-dir.

For example, with the following directory structure:

• Directoryprod

  • Directoryapp

    • terragrunt.hcl
  • Directorydb

    • terragrunt.hcl
• Directorystaging

  • Directoryapp

    • terragrunt.hcl
  • Directorydb

    • terragrunt.hcl

Running terragrunt run --all plan --queue-include-dir "prod/*" would process all directories, but the --all flag includes by default when no excludes are provided, so the stage stack would also be included by default.

Running terragrunt run --all plan --queue-include-dir "prod/*" --queue-strict-include tells Terragrunt to exclude by default, so it only include units prod/app and prod/db.

Danger

When using --queue-strict-include, all dependencies of included directories will be excluded if they are not explicitly included. This can lead to unexpected behavior if you’re not careful with your include patterns.

Always verify the modules that will be included before running destructive commands.

Type: bool

Environment Variables:

• TG_QUEUE_STRICT_INCLUDE