run

Usage

Run a command, passing arguments to an orchestrated tofu/terraform binary.

This is the explicit, and most flexible form of running an IaC command with Terragrunt. Shortcuts can be found in "terragrunt --help" for common use-cases.

Examples

Run the plan command.

terragrunt run plan
# Shortcut:
# terragrunt plan

Run the plan command, and pass additional arguments.

terragrunt run -- output -json
# Shortcut:
# terragrunt output -json

Running multiple units

Note that the run command is a more explicit and flexible way to run OpenTofu/Terraform commands in comparison to OpenTofu shortcuts.

The run command also supports the following flags that can be used to drive runs in multiple units:

• --all: Run the provided OpenTofu/Terraform command against all units in the current stack.
• --graph: Run the provided OpenTofu/Terraform command against the graph of dependencies for the unit in the current working directory.

Separating Arguments

You may, at times, need to explicitly separate the arguments used for Terragrunt from those used for OpenTofu/Terraform. In those circumstances, you can use the argument -- to separate the Terragrunt flags from the OpenTofu/Terraform flags.

terragrunt run -- plan -no-color

Caution

When using run --all plan with units that have dependencies (e.g. via dependency or dependencies blocks), the command will fail if those dependencies have never been deployed. This is because Terragrunt cannot resolve dependency outputs without existing state.

To work around this issue, use mock outputs in dependency blocks.

Caution

Do not set TF_PLUGIN_CACHE_DIR when using run --all. This can cause concurrent access issues with the provider cache. Instead, use Terragrunt’s built-in Provider Cache Server.

We are working with the OpenTofu team to improve this behavior in the future.

Caution

When using run --all with apply or destroy, Terragrunt automatically adds the -auto-approve flag due to limitations with shared stdin making individual approvals impossible.

Flags

--all

Run the specified OpenTofu/Terraform command on the stack of units in the current directory.

When this flag is set, Terragrunt will run the specified OpenTofu/Terraform command against all units in the current stack. This is useful when you want to apply changes across multiple units at once.

For example:

terragrunt run --all plan

This will run the plan command against all units in the current stack.

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

Note

Terragrunt has a notion of “external dependencies”. These are units that are not part of the current stack, from the perspective of the current working directory, but are dependencies of units that are part of the current stack.

When running an --all command, Terragrunt will discover any external dependencies and prompt you to confirm that you want to run them as well.

If you would like to suppress this prompt, you can use the --non-interactive flag. You can also prevent this behavior by setting --queue-exclude-external.

Danger

When running a run --all destroy command, Terragrunt will destroy all dependencies of the units under the current working directory, in addition to the units themselves by default!

If you wish to prevent external dependencies from being destroyed, add the --queue-exclude-external flag, or use the --exclude-dir flag once for each directory you wish to exclude.

Type: bool

Environment Variables:

• TG_ALL

--auth-provider-cmd

Run the provided command and arguments to authenticate Terragrunt dynamically when necessary.

The command and arguments used to obtain authentication credentials dynamically. If specified, Terragrunt runs this command whenever it might need authentication. This includes HCL parsing, where it might be useful to authenticate with a cloud provider before running HCL functions like get_aws_account_id where authentication has to already have taken place. It can also be useful for HCL functions like run_cmd where it may be useful to be authenticated before calling the function.

The output must be valid JSON of the following schema:

{
  "awsCredentials": {
    "ACCESS_KEY_ID": "",
    "SECRET_ACCESS_KEY": "",
    "SESSION_TOKEN": ""
  },
  "awsRole": {
    "roleARN": "",
    "sessionName": "",
    "duration": 0,
    "webIdentityToken": ""
  },
  "envs": {
    "ANY_KEY": ""
  }
}

This allows Terragrunt to acquire different credentials at runtime without changing any terragrunt.hcl configuration. You can use this flag to set arbitrary credentials for continuous integration, authentication with providers other than AWS and more.

As long as the standard output of the command passed to auth-provider-cmd results in JSON matching the schema above, corresponding environment variables will be set (and/or roles assumed) before Terragrunt begins parsing an terragrunt.hcl file or running an OpenTofu/Terraform command.

The simplest approach to leverage this flag is to write a script that fetches desired credentials, and emits them to STDOUT in the JSON format listed above:

#!/usr/bin/env bash

echo -n '{"envs": {"KEY": "a secret"}}'

You can use any technology for the authentication provider you’d like, however, as long as Terragrunt can execute it. The expected pattern for using this flag is to author a script/program that will dynamically fetch secret values from a secret store, etc. then emit them to STDOUT for consumption by Terragrunt.

Note that more specific configurations (e.g. awsCredentials) take precedence over less specific configurations (e.g. envs).

If you would like to set credentials for AWS with this method, you are encouraged to use awsCredentials instead of envs, as these keys will be validated to conform to the officially supported environment variables expected by the AWS SDK.

Similarly, if you would like Terragrunt to assume an AWS role on your behalf, you are encouraged to use the awsRole configuration instead of envs.

Other credential configurations will be supported in the future, but until then, if your provider authenticates via environment variables, you can use the envs field to fetch credentials dynamically from a secret store, etc before Terragrunt executes any IAC.

Note

The awsRole configuration is only used when the awsCredentials configuration is not present. If both are present, the awsCredentials configuration will take precedence.

Caution

When using iam-assume-role, AWS authentication takes place right before a Terraform run, after terragrunt.hcl files are fully parsed. This means HCL functions like get_aws_account_id and run_cmd will not run with the assumed role credentials. If you need roles to be assumed prior to parsing configurations, use auth-provider-cmd instead.

Type: string

Environment Variables:

• TG_AUTH_PROVIDER_CMD

--backend-require-bootstrap

When this flag is set, Terragrunt will throw an error if remote state needs to be created via the `backend bootstrap` command.

This flag provides a safety mechanism when working with remote state backends.

This is particularly useful in production environments where you want to ensure that:

1. All infrastructure for storing state is properly bootstrapped before Terragrunt runs any OpenTofu/Terraform commands.
2. Prevent accidental creation of state buckets in scenarios where they should already exist.

Without this flag, Terragrunt will attempt to create the remote state bucket automatically if it doesn’t exist (though this will change in the future).

Type: bool

Environment Variables:

• TG_BACKEND_REQUIRE_BOOTSTRAP

--config

The path to the Terragrunt config file. Default is terragrunt.hcl.

This flag allows you to specify a custom path to your Terragrunt configuration file. By default, Terragrunt looks for a file named terragrunt.hcl in the current directory.

This is useful when you:

• Have multiple Terragrunt configurations in the same directory.
• Want to use a different naming convention for your configuration files.
• Need to test alternative configurations without modifying the default file.

Example usage:

terragrunt run plan --config custom-config.hcl

Type: string

Environment Variables:

• TG_CONFIG

--dependency-fetch-output-from-state

Fetch dependency outputs directly from the state file instead of using `tofu output`.

This flag modifies how Terragrunt retrieves output values from dependent units. When enabled, Terragrunt will read the outputs directly from the state file instead of running terraform output or tofu output.

The main benefit this flag provides is performance. Reading directly from state is typically faster than executing the OpenTofu/Terraform binary to get the same outputs.

The limitation of this approach is that it is only supported by the S3 backend, and OpenTofu/Terraform may change the schema of the state file in the future, breaking this functionality.

Caution

Avoid using this flag without pinning the version of OpenTofu/Terraform you are using.

There is no guarantee that OpenTofu/Terraform will maintain the existing schema of their state files, so there is also no guarantee that the flag will work as expected in future versions of OpenTofu/Terraform. They have not changed the schema of the state file in a long time, but there is no guarantee that they will not change it in the future. We are coordinating with the OpenTofu team to encourage stability in the state file schema, unless significant performance improvements can be made to OpenTofu output fetching to make this flag unnecessary.

Tip

Direct output fetching is a performance optimization. For more details on performance optimizations, their tradeoffs, and other performance tips, read the dedicated Performance documentation.

Type: bool

Environment Variables:

• TG_DEPENDENCY_FETCH_OUTPUT_FROM_STATE

--disable-bucket-update

When this flag is set, Terragrunt will not update the remote state resources.

When enabled, Terragrunt will throw an error if it detects that remote state resources need to be updated.

This is useful in scenarios where:

• You want to ensure state bucket configurations remain unchanged during operations
• You have separate processes for managing state bucket configurations

The flag acts as a safety mechanism to prevent unintended modifications to your state storage infrastructure.

Type: bool

Environment Variables:

• TG_DISABLE_BUCKET_UPDATE

--disable-command-validation

When this flag is set, Terragrunt will not validate the tofu/terraform command.

This flag disables Terragrunt’s built-in validation of OpenTofu/Terraform commands. When enabled, Terragrunt will pass commands through to OpenTofu/Terraform without checking if they are valid or supported.

Type: bool

Environment Variables:

• TG_DISABLE_COMMAND_VALIDATION

--download-dir

The path to download OpenTofu/Terraform modules into. Default is .terragrunt-cache in the working directory.

Specifies a custom directory where Terragrunt will download and cache OpenTofu/Terraform modules.

By default, modules are downloaded to .terragrunt-cache in the working directory.

Note

The download directory (.terragrunt-cache by default) can grow significantly over time with multiple versions of modules.

Remember to add this directory to your .gitignore file and consider periodic cleanup of old cached content.

Type: string

Environment Variables:

• TG_DOWNLOAD_DIR

--engine-cache-path

Cache path for Terragrunt engine files.

Specifies the directory where Terragrunt will store its engine cache files. The engine cache helps improve performance by storing compiled configurations and other internal data.

When not specified, Terragrunt will use a default location in the system’s temporary directory.

You must also set the experimental-engine flag to enable engine usage.

Type: string

Environment Variables:

• TG_ENGINE_CACHE_PATH

--engine-log-level

Terragrunt engine log level.

Controls the verbosity of logs from the Terragrunt engine. This is separate from the main Terragrunt logging and specifically affects engine-related operations like configuration parsing and dependency resolution.

By default, the engine log level is set to that of the main Terragrunt logging level.

You must also set the experimental-engine flag to enable engine usage.

Type: string

Environment Variables:

• TG_ENGINE_LOG_LEVEL

--engine-skip-check

Skip checksum check for Terragrunt engine files.

When enabled, Terragrunt will skip the checksum validation of engine files.

This can be useful during development or testing, and is currently the only way to use self-developed engines.

Terragrunt currently only has support for verifying the signatures of official engines, though this will change in the future.

In the meantime, you are encouraged to download engines from a trusted source, verify the integrity of the engine manually, and then reference the local path to the engine in your Terragrunt configuration.

You must also set the experimental-engine flag to use engines.

Type: bool

Environment Variables:

• TG_ENGINE_SKIP_CHECK

--experimental-engine

Enable Terragrunt experimental engine.

Enables usage of Terragrunt IaC engines.

IaC engines are still experimental, as the API is unstable and may change in future minor versions of Terragrunt.

If you are using a remote custom engine, you must also set the engine-skip-check flag to skip the signature check for the engine.

Type: bool

Environment Variables:

• TG_EXPERIMENTAL_ENGINE

--feature

Set feature flags for the HCL code.

Allows enabling or disabling specific features in the HCL code.

To learn more about feature flags, see the Feature Flags feature documentation.

Type: string

Environment Variables:

• TG_FEATURE

--graph

Run the provided OpenTofu/Terraform command against the graph of dependencies for the unit in the current working directory.

When this flag is set, Terragrunt will run the specified OpenTofu/Terraform command against the graph of dependencies for the unit in the current working directory. The graph consists of all units that depend on the unit in the current working directory via a dependency or dependencies blocks, plus all the units that depend on those units, and all the units that depend on those units, and so on, recursively up the tree, up to the Git repository root.

The command will be executed following the order of dependencies: it’ll run on the unit in the current working directory first, then on units that depend on it directly, then on the units that depend on those units, and so on. Note that if the command is destroy, it will run in the opposite order (the final dependents, then their dependencies, etc. up to the unit you ran the command in).

Example Usage

Given the following dependency graph:

Running terragrunt run --graph plan in the eks module will lead to the following execution order:

Group 1
- Module project/eks

Group 2
- Module project/services/eks-service-1
- Module project/services/eks-service-2

Group 3
- Module project/services/eks-service-2-v2
- Module project/services/eks-service-3
- Module project/services/eks-service-5

Group 4
- Module project/services/eks-service-3-v2
- Module project/services/eks-service-4

Group 5
- Module project/services/eks-service-3-v3

Notes:

• lambda units aren’t included in the graph because they are not dependent on the eks unit
• Execution is from bottom up based on dependencies

Running terragrunt run --graph destroy in the eks unit will lead to the following execution order:

Group 1
- Module project/services/eks-service-2-v2
- Module project/services/eks-service-3-v3
- Module project/services/eks-service-4
- Module project/services/eks-service-5

Group 2
- Module project/services/eks-service-3-v2

Group 3
- Module project/services/eks-service-3

Group 4
- Module project/services/eks-service-1
- Module project/services/eks-service-2

Group 5
- Module project/eks

Notes:

• Execution is in reverse order; first are destroyed “top” units and in the end eks
• lambda units aren’t affected at all

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

Caution

When running graph destroy, the execution order is reversed compared to other commands. Dependencies will be destroyed in reverse order to ensure resources are safely removed (dependents are destroyed before their dependencies).

Always verify the execution plan before running destructive commands.

Danger

External dependencies (units outside your current working directory) are not automatically included in graph runs.

You must explicitly include them using --queue-include-external if they need to be part of the execution.

Type: bool

Environment Variables:

• TG_GRAPH

--iam-assume-role

Assume the specified IAM role before executing OpenTofu/Terraform.

Specifies an IAM role ARN that Terragrunt should assume before executing OpenTofu/Terraform commands. This is useful for managing resources across different AWS accounts or with different permission sets.

For more information on how to use this flag, and how it differs from other ways of managing authentication with Terragrunt, see the Authentication feature documentation.

Type: string

Environment Variables:

• TG_IAM_ASSUME_ROLE

--iam-assume-role-duration

Session duration for IAM Assume Role session.

Specifies how long the temporary credentials should remain valid when assuming an IAM role. This flag is only used when iam-assume-role is specified.

For more information on how to use this flag, and how it differs from other ways of managing authentication with Terragrunt, see the Authentication feature documentation.

Type: string

Environment Variables:

• TG_IAM_ASSUME_ROLE_DURATION

--iam-assume-role-session-name

Name for the IAM Assumed Role session.

Specifies a custom session name when assuming an IAM role. This flag is only used when iam-assume-role is specified.

For more information on how to use this flag, and how it differs from other ways of managing authentication with Terragrunt, see the Authentication feature documentation.

Type: string

Environment Variables:

• TG_IAM_ASSUME_ROLE_SESSION_NAME

--iam-assume-role-web-identity-token

For AssumeRoleWithWebIdentity, the WebIdentity token.

Specifies the WebIdentity token to use when assuming an IAM role using web identity federation. This flag is only used when iam-assume-role is specified.

For more information on how to use this flag, and how it differs from other ways of managing authentication with Terragrunt, see the Authentication feature documentation.

Type: string

Environment Variables:

• TG_IAM_ASSUME_ROLE_WEB_IDENTITY_TOKEN

--inputs-debug

Write debug.tfvars to working folder to help root-cause issues.

When enabled, Terragrunt will write a debug.tfvars file to the working directory. This file contains the resolved input values and can be useful for debugging configuration issues.

To learn more about how to use this flag, see the Debugging guide.

Type: bool

Environment Variables:

• TG_INPUTS_DEBUG

--no-auto-approve

Don't automatically append '-auto-approve' to the underlying OpenTofu/Terraform commands run with 'run --all'.

When enabled, Terragrunt will not automatically append the -auto-approve flag to destructive commands like apply or destroy when running with --all. This means you’ll be prompted for confirmation before making changes.

Type: bool

Environment Variables:

• TG_NO_AUTO_APPROVE

--no-auto-init

Don't automatically run init on tofu/terraform commands.

When enabled, Terragrunt will not automatically run init before other OpenTofu/Terraform commands.

To learn more about how to use this flag, see the Auto-init feature documentation.

Caution

When --no-auto-init is enabled, you must manually run terragrunt init if needed. Terragrunt will fail if it detects that initialization is required but auto-init is disabled.

This is particularly important when using custom plugin directories or when working in CI/CD environments.

Type: bool

Environment Variables:

• TG_NO_AUTO_INIT

--no-auto-retry

Don't automatically retry commands which fail with transient errors.

When enabled, Terragrunt will not automatically retry commands that fail with transient errors (like network timeouts). By default, Terragrunt will retry such commands a limited number of times.

To learn more about how Terragrunt handles retries, see the Errors section of the Runtime Control feature documentation.

Type: bool

Environment Variables:

• TG_NO_AUTO_RETRY

--no-destroy-dependencies-check

Disables Terragrunt's dependency validation during destroy operations.

When enabled, Terragrunt will not verify if there are dependent units that would be affected by destroying the current unit.

This results in faster destroy operations, but may result in orphaned resources.

Caution

Disabling dependency checks during destroy operations can lead to orphaned resources or broken infrastructure dependencies.

Type: bool

Environment Variables:

• TG_NO_DESTROY_DEPENDENCIES_CHECK

--parallelism

Parallelism for --all commands.

Sets the maximum number of concurrent operations when running commands with --all. This helps control resource usage and API rate limits when working with multiple units.

Caution

When using --parallelism with provider caching, terraform init is always executed sequentially if OpenTofu/Terraform provider plugin cache is configured.

To safely run concurrent operations with provider caching, enable the Provider Cache Server instead.

Type: integer

Environment Variables:

• TG_PARALLELISM

--provider-cache

Enables Terragrunt's provider caching.

When enabled, Terragrunt will use its provider caching system to speed up provider downloads.

For more information, see the Provider Cache Server feature documentation.

Note

The tofu init command is always executed sequentially if the provider plugin cache is used without the Provider Cache Server.

Type: bool

Environment Variables:

• TG_PROVIDER_CACHE

--provider-cache-dir

The path to the Terragrunt provider cache directory. By default, 'terragrunt/providers' folder in the user cache directory.

Specifies the directory where Terragrunt will store cached provider files. This flag is only used when the Provider Cache Server is enabled.

Type: string

Environment Variables:

• TG_PROVIDER_CACHE_DIR

--provider-cache-hostname

The hostname of the Terragrunt Provider Cache server. By default, 'localhost'.

Sets the hostname for connecting to the Provider Cache server. This flag is only used when the Provider Cache Server is enabled.

Type: string

Environment Variables:

• TG_PROVIDER_CACHE_HOSTNAME

--provider-cache-port

The port of the Terragrunt Provider Cache server. By default, assigned automatically.

Specifies the port number for connecting to the Provider Cache server. This flag is only used when the Provider Cache Server is enabled.

Type: string

Environment Variables:

• TG_PROVIDER_CACHE_PORT

--provider-cache-registry-names

The list of remote registries to cached by Terragrunt Provider Cache server. By default, 'registry.terraform.io', 'registry.opentofu.org'.

Specifies which provider registries should be cached by the Provider Cache server. This flag is only used when the Provider Cache Server is enabled.

Type: string

Environment Variables:

• TG_PROVIDER_CACHE_REGISTRY_NAMES

--provider-cache-token

The token for authentication to the Terragrunt Provider Cache server. By default, assigned automatically.

Sets the authentication token for connecting to the Provider Cache server. This flag is only used when the Provider Cache Server is enabled.

Type: string

Environment Variables:

• TG_PROVIDER_CACHE_TOKEN

--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

The glob curly braces expansion behaves differently when using environment variables versus command line parameters.

Use TG_QUEUE_EXCLUDE_DIR="foo/module,bar/module" instead of TG_QUEUE_EXCLUDE_DIR="{foo,bar}/module".

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 containing Unix-style globs of directories to exclude from the queue of Units to run.

Specifies a file containing patterns of directories to exclude when running commands with --all.

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

Type: string

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.

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

--report-file

The path where a run report should be generated.

By default, the format of the report will be automatically detected based on the file extension. A .csv extension will generate a CSV report, and a .json extension will generate a JSON report. Anything else will default to generating a CSV report.

To explicitly specify the format of the report, use the report-format flag.

For more information, see the Run Report feature.

Type: string

Environment Variables:

• TG_REPORT_FILE

--report-file

The format of the run report.

The supported formats are:

• csv
• json

The default is csv.

For more information, see the Run Report feature.

Type: string

Environment Variables:

• TG_REPORT_FORMAT

----report-schema-file

When passed in, a JSON schema for the report will be generated at the specified path.

This is useful when you need a programmatic way to validate that the report conforms to an expected schema.

Example

terragrunt run --all plan --report-schema-file report.schema.json

The schema will be generated at the given path in the current working directory.

For more information, see the Run Report feature.

Type: string

Environment Variables:

• TG_REPORT_SCHEMA_FILE

--source

Download OpenTofu/Terraform configurations from the specified source into a temporary folder, and run Terraform in that temporary folder.

Specifies a source URL where Terragrunt should download the OpenTofu/Terraform configuration. This overrides any source parameters specified in the Terragrunt configuration files.

The configuration will be downloaded into a temporary folder, and Terragrunt will execute OpenTofu/Terraform commands in that folder.

Example:

terragrunt run plan --source github.com/example/infrastructure//modules/vpc

This is particularly useful when:

• Testing changes to modules without modifying the source in your configuration.
• Using a specific version or branch of your infrastructure modules.
• Running configurations from a different source than what’s specified in your Terragrunt files.

Type: string

Environment Variables:

• TG_SOURCE

--source-map

Replace any source URL (including the source URL of a config pulled in with dependency blocks) that has root source with dest.

Allows you to replace source URLs that match a specified pattern with a different URL. This affects both direct source references and sources specified in dependency blocks.

The format is source-regex=replacement-source.

For example:

terragrunt run plan --source-map "git::ssh://git@github.com/org/repo.git=../local/repo"

This will replace any source URL that matches github.com/example/infrastructure//modules/vpc with github.com/example/infrastructure//modules/vpc-new.

Caution

Source mapping only performs literal matches on the URL portion. For example, a map key of ssh://git@github.com/org/repo.git will not match sources of the form git::ssh://git@github.com/org/repo.git. The latter requires a map key of git::ssh://git@github.com/org/repo.git.

Type: string

Environment Variables:

• TG_SOURCE_MAP

--source-update

Delete the contents of the temporary folder to clear out any old, cached source code before downloading new source code into it.

When enabled, Terragrunt will delete any existing content in the temporary download directory before fetching new source code into it. This ensures you’re working with a fresh copy of the source code.

Example:

terragrunt run plan --source-update

Type: bool

Environment Variables:

• TG_SOURCE_UPDATE

--summary-disable

Disables the summary output at the end of a run.

When enabled, Terragrunt will disable the summary output at the end of a run.

For more information, see the Run Report feature.

Type: bool

Environment Variables:

• TG_SUMMARY_DISABLE

--summary-unit-duration

Shows the duration of each unit in the run summary.

When enabled, Terragrunt will show the duration of each unit in the run summary. The units are sorted by duration, with the longest-running units shown first.

For more information, see the Run Report feature.

Type: bool

Environment Variables:

• TG_SUMMARY_UNIT_DURATION

--tf-forward-stdout

If specified, the output of OpenTofu/Terraform commands will be printed as is, without being integrated into the Terragrunt log.

By default, Terragrunt integrates OpenTofu/Terraform output into its own logging system. When this flag is enabled, OpenTofu/Terraform output will be printed directly to stdout without Terragrunt’s logging wrapper.

For example, without --tf-forward-stdout:

14:19:25.081 INFO   [app] Running command: tofu plan -input=false
14:19:25.174 STDOUT [app] tofu: OpenTofu used the selected providers to generate the following execution
14:19:25.174 STDOUT [app] tofu: plan. Resource actions are indicated with the following symbols:
14:19:25.174 STDOUT [app] tofu:   + create
14:19:25.174 STDOUT [app] tofu: OpenTofu will perform the following actions:

With --tf-forward-stdout:

14:19:25.081 INFO   [app] Running command: tofu plan -input=false

OpenTofu used the selected providers to generate the following execution
plan. Resource actions are indicated with the following symbols:
  + create

OpenTofu will perform the following actions:

Type: bool

Environment Variables:

• TG_TF_FORWARD_STDOUT

--tf-path

Path to the OpenTofu/Terraform binary. Default is tofu (on PATH).

Specifies the path to the OpenTofu/Terraform binary that Terragrunt should use. By default, Terragrunt will look for a binary named tofu in your system’s PATH.

This is useful when:

• You have multiple versions of OpenTofu/Terraform installed.
• The binary is not in your PATH.
• You want to use a specific version for certain operations.
• You want to switch between OpenTofu and Terraform binaries.

Example:

terragrunt run plan --tf-path=/usr/local/bin/tofu

Note that if you only have terraform installed, and it is available in your PATH, Terragrunt will automatically use that binary.

NOTE: This will override the terraform binary that is used by terragrunt in all instances, including dependency lookups. This setting will also override any terraform_binary configuration values specified in the terragrunt.hcl config for both the top level, and dependency lookups.

Type: string

Environment Variables:

• TG_TF_PATH

--units-that-include

If flag is set, 'run --all' will only run the command against Terragrunt units that include the specified file.

When specified, Terragrunt will only run commands against units that include the specified configuration file. This is useful for targeting specific configurations that share common included files.

For example, with the following directory structure:

• Directorydev

  • Directoryapp

    • terragrunt.hcl
  • Directorydb

    • terragrunt.hcl
• Directoryprod

  • Directoryapp

    • terragrunt.hcl
  • Directorydb

    • terragrunt.hcl
• Directory_envcommon

  • app.hcl
  • db.hcl

If both dev/app/terragrunt.hcl and prod/app/terragrunt.hcl include files from _envcommon, you can target all units that include the app.hcl file:

terragrunt run --all --units-that-include=./_envcommon/app.hcl plan

This will only run the command against units that include the app.hcl file.

Note: This flag is functionally covered by the --queue-include-units-reading flag, but is more explicitly focused on the include configuration block.

Type: string

Environment Variables:

• TG_UNITS_THAT_INCLUDE

--use-partial-parse-config-cache

Enables caching of includes during partial parsing operations. Will also be used for the --iam-role option if provided.

This flag can be used to drastically decrease time required for parsing Terragrunt configuration files. The effect will only show if a lot of similar includes are expected such as the root terragrunt configuration (e.g. root.hcl) include.

NOTE: This is an experimental feature, use with caution.

The reason you might want to use this flag is that Terragrunt frequently only needs to perform a partial parse of Terragrunt configurations.

This is the case for scenarios like:

• Building the Directed Acyclic Graph (DAG) during a run --all command where only the dependency blocks need to be evaluated to determine run order.
• Parsing the terraform block to determine state configurations for fetching dependency outputs.
• Determining whether Terragrunt execution behavior has to change like for prevent_destroy or skip flags in configuration.

These configurations are generally safe to cache, but due to the nature of HCL being a dynamic configuration language, there are some edge cases where caching these can lead to incorrect behavior.

Once this flag has been tested thoroughly, we will consider making it the default behavior.

Caution

This is an experimental feature. While it can significantly improve performance with frequently included configurations, the caching behavior may lead to unexpected results in some edge cases due to HCL’s dynamic nature.

Test thoroughly in your environment before using in production environments.

Type: bool

Environment Variables:

• TG_USE_PARTIAL_PARSE_CONFIG_CACHE