This page documents the CLI commands and options available with Terragrunt:
Terragrunt supports the following CLI commands:
Terragrunt is an orchestration tool for OpenTofu/Terraform, so except for a few of the special commands defined in these docs,
Terragrunt forwards all other commands to OpenTofu/Terraform. For example, when you run terragrunt apply
, Terragrunt executes
tofu apply
/terraform apply
.
Examples:
terragrunt plan
terragrunt apply
terragrunt output
terragrunt destroy
# etc
Run terraform --help
to get the full list.
Runs the provided OpenTofu/Terraform command against a stack. The command will recursively find terragrunt units in the current directory tree and run the OpenTofu/Terraform command in dependency order (unless the command is destroy, in which case the command is run in reverse dependency order).
Make sure to read Execute OpenTofu/Terraform commands on multiple modules at once for context.
Example:
terragrunt run-all apply
This will recursively search the current working directory for any folders that contain Terragrunt units and run
apply
in each one, concurrently, while respecting ordering defined via
dependency
and
dependencies
blocks.
[WARNING] Use run-all
with care if you have unapplied dependencies.
If you have a stack of Terragrunt units with dependencies between them—either via dependency
blocks
or terraform_remote_state
data sources—and
you’ve never deployed them, then commands like run-all plan
will fail,
as it will not be possible to resolve the dependency
blocks
or terraform_remote_state
data sources!
The solution for this is to take advantage of mock outputs in dependency blocks.
[WARNING] Do not set TF_PLUGIN_CACHE_DIR when using run-all
Instead take advantage of the built-in Provider Cache Server that mitigates some of the limitations of using the OpenTofu/Terraform Provider Plugin Cache directly.
Note that we are working with the OpenTofu team to improve this behavior so that you don’t have to worry about this.
[NOTE] Using run-all
with apply
or destroy
silently adds the -auto-approve
flag to the command line
arguments passed to OpenTofu/Terraform due to issues with shared stdin
making individual approvals impossible.
[NOTE] Using the OpenTofu/Terraform -detailed-exitcode
flag with the run-all
command results in an aggregate exit code being returned, rather than the exit code of any particular unit.
The algorithm for determining the aggregate exit code is as follows:
DEPRECATED: Use run-all plan
instead.
Display the plans of a stack
by running terragrunt plan
in each subfolder. Make sure to read Execute OpenTofu/Terraform
commands on multiple modules at once for
context.
Example:
terragrunt run-all plan
This will recursively search the current working directory for any folders that contain Terragrunt modules and run
plan
in each one, concurrently, while respecting ordering defined via
dependency
and
dependencies
blocks.
[WARNING] run-all plan
is currently broken for certain use cases. If you have a stack of Terragrunt modules with
dependencies between them—either via dependency
blocks or terraform_remote_state
data sources—and you’ve never
deployed them, then run-all plan
will fail as it will not be possible to resolve the dependency
blocks or
terraform_remote_state
data sources! Please see here for more
information.
DEPRECATED: Use run-all apply
instead.
Apply a stack
by running terragrunt apply
in each subfolder. Make sure to read Execute OpenTofu/Terraform
commands on multiple modules at once for
context.
Example:
terragrunt apply-all
This will recursively search the current working directory for any folders that contain Terragrunt modules and run
apply
in each one, concurrently, while respecting ordering defined via
dependency
and
dependencies
blocks.
[NOTE] Using apply-all
silently adds the -auto-approve
flag to the command line arguments passed to OpenTofu/Terraform
due to issues with shared stdin
making individual approvals impossible. Please see here for more
information
DEPRECATED: Use run-all output
instead.
Display the outputs of a stack
by running terragrunt output
in each subfolder. Make sure to read Execute OpenTofu/Terraform
commands on multiple modules at once for
context.
Example:
terragrunt output-all
This will recursively search the current working directory for any folders that contain Terragrunt modules and run
output
in each one, concurrently, while respecting ordering defined via
dependency
and
dependencies
blocks.
[WARNING] output-all
is currently broken for certain use cases. If you have a stack of Terragrunt modules with
dependencies between them—either via dependency
blocks or terraform_remote_state
data sources—and you’ve never
deployed them, then output-all
will fail as it will not be possible to resolve the dependency
blocks or
terraform_remote_state
data sources! Please see here for more
information.
DEPRECATED: Use run-all destroy
instead.
Destroy a stack
by running terragrunt destroy
in each subfolder. Make sure to read Execute OpenTofu/Terraform
commands on multiple modules at once for
context.
Example:
terragrunt destroy-all
This will recursively search the current working directory for any folders that contain Terragrunt modules and run
destroy
in each one, concurrently, while respecting ordering defined via
dependency
and
dependencies
blocks.
[NOTE] Using destroy-all
silently adds the -auto-approve
flag to the command line arguments passed to OpenTofu/Terraform
due to issues with shared stdin
making individual approvals impossible. Please see here for more
information
DEPRECATED: Use run-all validate
instead.
Validate stack
by running terragrunt validate
in each subfolder. Make sure to read Execute OpenTofu/Terraform
commands on multiple modules at once for
context.
Example:
terragrunt validate-all
This will recursively search the current working directory for any folders that contain Terragrunt modules and run
validate
in each one, concurrently, while respecting ordering defined via
dependency
and
dependencies
blocks.
Emits limited terragrunt state on stdout
in a JSON format and exits.
Example:
terragrunt terragrunt-info
Might produce output such as:
{
"ConfigPath": "/example/path/terragrunt.hcl",
"DownloadDir": "/example/path/.terragrunt-cache",
"IamRole": "",
"TerraformBinary": "terraform",
"TerraformCommand": "terragrunt-info",
"WorkingDir": "/example/path"
}
Emits information about the input variables that are configured with the given terragrunt configuration. Specifically, this command will print out unused inputs (inputs that are not defined as an OpenTofu/Terraform variable in the corresponding module) and undefined required inputs (required OpenTofu/Terraform variables that are not currently being passed in).
Example:
> terragrunt validate-inputs
The following inputs passed in by terragrunt are unused:
- foo
- bar
The following required inputs are missing:
- baz
Note that this only checks for variables passed in in the following ways:
Configured inputs
attribute.
var files defined on terraform.extra_arguments
blocks using required_var_files
and optional_var_files
.
-var-file
and -var
CLI arguments defined on terraform.extra_arguments
using arguments
.
-var-file
and -var
CLI arguments passed to terragrunt.
Automatically loaded var files (terraform.tfvars
, terraform.tfvars.json
, *.auto.tfvars
, *.auto.tfvars.json
)
TF_VAR
environment variables defined on terraform.extra_arguments
blocks.
TF_VAR
environment variables defined in the environment.
Be aware that other ways to pass variables to tofu
/terraform
are not checked by this command.
Additionally, there are two modes in which the validate-inputs
command can be run: relaxed (default) and strict.
If you run the validate-inputs
command without flags, relaxed mode will be enabled by default. In relaxed mode, any unused variables
that are passed, but not used by the underlying OpenTofu/Terraform configuration, will generate a warning, but not an error. Missing required variables will always return an error, whether validate-inputs
is running in relaxed or strict mode.
To enable strict mode, you can pass the --terragrunt-strict-validate
flag like so:
> terragrunt validate-inputs --terragrunt-strict-validate
When running in strict mode, validate-inputs
will return an error if there are unused inputs.
This command will exit with an error if terragrunt detects any unused inputs or undefined required inputs.
Prints the terragrunt dependency graph, in DOT format, to stdout
. You can generate charts from DOT format using tools
such as GraphViz.
Example:
terragrunt graph-dependencies
This will recursively search the current working directory for any folders that contain Terragrunt modules and build
the dependency graph based on dependency
and
dependencies
blocks. This may produce output such as:
digraph {
"mgmt/bastion-host" ;
"mgmt/bastion-host" -> "mgmt/vpc";
"mgmt/bastion-host" -> "mgmt/kms-master-key";
"mgmt/kms-master-key" ;
"mgmt/vpc" ;
"stage/backend-app" ;
"stage/backend-app" -> "stage/vpc";
"stage/backend-app" -> "mgmt/bastion-host";
"stage/backend-app" -> "stage/mysql";
"stage/backend-app" -> "stage/search-app";
"stage/frontend-app" ;
"stage/frontend-app" -> "stage/vpc";
"stage/frontend-app" -> "mgmt/bastion-host";
"stage/frontend-app" -> "stage/backend-app";
"stage/mysql" ;
"stage/mysql" -> "stage/vpc";
"stage/redis" ;
"stage/redis" -> "stage/vpc";
"stage/search-app" ;
"stage/search-app" -> "stage/vpc";
"stage/search-app" -> "stage/redis";
"stage/vpc" ;
"stage/vpc" -> "mgmt/vpc";
}
Recursively find hcl files and rewrite them into a canonical format.
Example:
terragrunt hclfmt
This will recursively search the current working directory for any folders that contain Terragrunt configuration files
and run the equivalent of tofu fmt
/terraform fmt
on them.
Find all hcl files from the configuration stack and validate them.
Example:
terragrunt hclvalidate
This will search all hcl files from the configuration stack in the current working directory and run the equivalent
of tofu validate
/terraform validate
on them.
For convenience in programmatically parsing these findings, you can also pass the --terragrunt-hclvalidate-json
flag to output the results in JSON format.
Example:
terragrunt hclvalidate --terragrunt-hclvalidate-json
In addition, you can pass the --terragrunt-hclvalidate-show-config-path
flag to only output paths of the invalid config files, delimited by newlines. This can be especially useful when combined with the terragrunt-excludes-file flag.
Example:
terragrunt hclvalidate --terragrunt-hclvalidate-show-config-path
Overwrite settings on nested AWS providers to work around several OpenTofu/Terraform bugs. Due to
issue #13018 and
issue #26211, the import
command may fail if your OpenTofu/Terraform
code uses a module that has a provider
block nested within it that sets any of its attributes to computed values.
This command is a hacky attempt at working around this problem by allowing you to temporarily hard-code those
attributes so import
can work.
You specify which attributes to hard-code using the --terragrunt-override-attr
option,
passing it ATTR=VALUE
, where ATTR
is the attribute name and VALUE
is the new value. VALUE
is assumed to be a
json encoded string, which means that you must have quotes (e.g., --terragrunt-override-attr 'region="eu-west-1"'
).
Additionally, note that ATTR
can specify attributes within a nested block by specifying <BLOCK>.<ATTR>
, where
<BLOCK>
is the block name.
For example, let’s say you had a provider
block in a module that looked like this:
provider "aws" {
region = var.aws_region
allowed_account_ids = var.allowed_account_ids
assume_role {
role_arn = var.role_arn
}
}
Both the region
and role_arn
parameters are set to dynamic values, which will trigger those OpenTofu/Terraform bugs. To work
around it, run the following command:
# NOTE: The single quotes around the args is to allow you to pass through the " character in the args via bash quoting
# rules.
terragrunt aws-provider-patch \
--terragrunt-override-attr 'region="eu-west-1"' \
--terragrunt-override-attr 'assume_role.role_arn=""' \
--terragrunt-override-attr 'allowed_account_ids=["00000000"]'
When you run the command above, Terragrunt will:
tofu init
/terraform init
to download the code for all your modules into .terraform/modules
..terraform/modules
, find AWS provider
blocks, and for each one, hard-code:
region
param to "eu-west-1"
.role_arn
within the assume_role
block to ""
.allowed_account_ids
param to ["0000000"]
.The result will look like this:
provider "aws" {
region = "eu-west-1"
allowed_account_ids = ["0000000"]
assume_role {
role_arn = ""
}
}
This should allow you to run import
on the module and work around those OpenTofu/Terraform bugs. When you’re done running
import
, remember to delete your overridden code! E.g., Delete the .terraform
or .terragrunt-cache
folders.
Render out the final interpreted terragrunt.hcl
file (that is, with all the includes merged, dependencies
resolved/interpolated, function calls executed, etc) as json.
Example:
The following terragrunt.hcl
:
locals {
aws_region = "us-east-1"
}
inputs = {
aws_region = local.aws_region
}
Renders to the following terragrunt_rendered.json
:
{
"locals": { "aws_region": "us-east-1" },
"inputs": { "aws_region": "us-east-1" }
// NOTE: other attributes are omitted for brevity
}
You can use the CLI option --terragrunt-json-out
to configure where terragrunt renders out the json representation.
To generate json with metadata can be specified argument --with-metadata
which will add metadata to the json output.
Example:
{
"inputs": {
"aws_region": {
"metadata": {
"found_in_file": "/example/terragrunt.hcl"
},
"value": "us-east-1"
}
},
"locals": {
"aws_region": {
"metadata": {
"found_in_file": "/example/terragrunt.hcl"
},
"value": "us-east-1"
}
}
// NOTE: other attributes are omitted for brevity
}
Output groups of modules ordered for apply (or destroy) as a list of list in JSON.
Example:
terragrunt output-module-groups <sub-command>
Optional sub-commands:
This will recursively search the current working directory for any folders that contain Terragrunt modules and build
the dependency graph based on dependency
and
dependencies
blocks and output the graph as a JSON list of list (unless the sub-command is destroy, in which case the command will output the reverse dependency order).
This can be be useful in several scenarios, such as in CICD, when determining apply order or searching for all files to apply with CLI options
such as --terragrunt-modules-that-include
This may produce output such as:
{
"Group 1": ["stage/frontend-app"],
"Group 2": ["stage/backend-app"],
"Group 3": ["mgmt/bastion-host", "stage/search-app"],
"Group 4": ["mgmt/kms-master-key", "stage/mysql", "stage/redis"],
"Group 5": ["stage/vpc"],
"Group 6": ["mgmt/vpc"]
}
Generate Terragrunt files from existing OpenTofu/Terraform modules.
More details in scaffold section.
Launch the user interface for searching and managing your module catalog.
More details in catalog section.
Run the provided OpenTofu/Terraform command against the graph of dependencies for the module in the current working directory. The graph consists of all modules that depend on the module in the current working directory via a depends_on
or dependencies
block, plus all the modules that depend on those modules, and all the modules that depend on those modules, and so on, recursively up the tree, up to the Git repository root, or the path specified via the optional --terragrunt-graph-root
argument.
The Command will be executed following the order of dependencies: so it’ll run on the module in the current working directory first, then on modules that depend on it directly, then on the modules that depend on those modules, and so on. Note that if the command is destroy
, it will execute in the opposite order of the dependencies.
Example: Having below dependencies:
Running terragrunt graph apply
in 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
modules aren’t included in the graph, because they are not dependent on eks
module.Running terragrunt graph destroy
in eks
module 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:
eks
lambda
modules aren’t affected at allRunning terragrunt graph apply
in services/eks-service-3
:
Group 1
- Module project/services/eks-service-3
Group 2
- Module project/services/eks-service-3-v2
- Module project/services/eks-service-4
Group 3
- Module project/services/eks-service-3-v3
Notes:
eks-service-3
Running terragrunt graph destroy
in services/eks-service-3
:
Group 1
- Module project/services/eks-service-3-v3
- Module project/services/eks-service-4
Group 2
- Module project/services/eks-service-3-v2
Group 3
- Module project/services/eks-service-3
Notes:
eks-service-3
Terragrunt forwards all options to OpenTofu/Terraform. The only exceptions are --version
and arguments that start with the
prefix --terragrunt-
(e.g., --terragrunt-config
). The currently available options are:
CLI Arg: --terragrunt-config
Environment Variable: TERRAGRUNT_CONFIG
Requires an argument: --terragrunt-config /path/to/terragrunt.hcl
A custom path to the terragrunt.hcl
or terragrunt.hcl.json
file. The
default path is terragrunt.hcl
(preferred) or terragrunt.hcl.json
in the current directory (see
Configuration for a slightly more nuanced
explanation). This argument is not used with the run-all
commands.
CLI Arg: --terragrunt-tfpath
Environment Variable: TERRAGRUNT_TFPATH
Requires an argument: --terragrunt-tfpath /path/to/terraform-binary
A custom path to the OpenTofu/Terraform binary. The default is tofu
in a directory on your PATH.
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.
CLI Arg: --terragrunt-no-auto-init
Environment Variable: TERRAGRUNT_NO_AUTO_INIT
(set to true
)
(Prior to Terragrunt v0.48.6, this environment variable was called TERRAGRUNT_AUTO_INIT
(set to false
), and is still available for backwards compatibility)
When passed in, don’t automatically run terraform init
when other commands are run (e.g. terragrunt apply
). Useful
if you want to pass custom arguments to terraform init
that are specific to a user or execution environment, and
therefore cannot be specified as extra_arguments
. For example, -plugin-dir
. You must run terragrunt init
yourself in this case if needed. terragrunt
will fail if it detects that init
is needed, but auto init is
disabled. See Auto-Init
CLI Arg: --terragrunt-no-auto-approve
Environment Variable: TERRAGRUNT_NO_AUTO_APPROVE
(set to true
)
(Prior to Terragrunt v0.48.6, this environment variable was called TERRAGRUNT_AUTO_APPROVE
(set to false
), and is still available for backwards compatibility)
Commands:
When passed in, Terragrunt will no longer automatically append -auto-approve
to the underlying OpenTofu/Terraform commands run
with run-all
. Note that due to the interactive prompts, this flag will also automatically assume
--terragrunt-parallelism 1
.
CLI Arg: --terragrunt-no-auto-retry
Environment Variable: TERRAGRUNT_NO_AUTO_RETRY
(set to true
)
(Prior to Terragrunt v0.48.6, this environment variable was called TERRAGRUNT_AUTO_RETRY
(set to false
), and is still available for backwards compatibility)
When passed in, don’t automatically retry commands which fail with transient errors. See Auto-Retry
CLI Arg: --terragrunt-non-interactive
Environment Variable: TERRAGRUNT_NON_INTERACTIVE
(set to true
)
(Prior to Terragrunt v0.48.6, this environment variable was called TF_INPUT
(set to false
), and is still available for backwards compatibility. NOTE: TF_INPUT is native to OpenTofu/Terraform!)
When passed in, don’t show interactive user prompts. This will default the answer for all Terragrunt (not OpenTofu/Terraform) prompts to yes
except for
the listed cases below. This is useful if you need to run Terragrunt in an automated setting (e.g. from a script). May
also be specified with the TF_INPUT environment variable.
This setting will default to no
for the following cases:
Note that this does not impact the behavior of OpenTofu/Terraform commands invoked by Terragrunt.
e.g.
terragrunt --terragrunt-non-interactive apply -auto-approve
Is how you would make Terragrunt apply without any user prompts from Terragrunt or OpenTofu/Terraform.
CLI Arg: --terragrunt-working-dir
Environment Variable: TERRAGRUNT_WORKING_DIR
Requires an argument: --terragrunt-working-dir /path/to/working-directory
Set the directory where Terragrunt should execute the terraform
command. Default is the current working directory.
Note that for the run-all
commands, this parameter has a different meaning: Terragrunt will apply or destroy all the
OpenTofu/Terraform modules in the subfolders of the terragrunt-working-dir
, running terraform
in the root of each module it
finds.
CLI Arg: --terragrunt-download-dir
Environment Variable: TERRAGRUNT_DOWNLOAD
Requires an argument: --terragrunt-download-dir /path/to/dir-to-download-terraform-code
The path where to download OpenTofu/Terraform code when using remote OpenTofu/Terraform
configurations.
Default is .terragrunt-cache
in the working directory. We recommend adding this folder to your .gitignore
.
CLI Arg: --terragrunt-source
Environment Variable: TERRAGRUNT_SOURCE
Requires an argument: --terragrunt-source /path/to/local-terraform-code
Download OpenTofu/Terraform configurations from the specified source into a temporary folder, and run OpenTofu/Terraform in that temporary
folder. The source should use the same syntax as the OpenTofu/Terraform module
source parameter. If you specify this argument for the run-all
commands, Terragrunt will assume this is the local file path for all of your OpenTofu/Terraform modules, and for each module
processed by the run-all
command, Terragrunt will automatically append the path of source
parameter in each module
to the --terragrunt-source
parameter you passed in.
CLI Arg: --terragrunt-source-map
Environment Variable: TERRAGRUNT_SOURCE_MAP
(encoded as comma separated value, e.g., source1=dest1,source2=dest2
)
Requires an argument: --terragrunt-source-map git::ssh://github.com=/path/to/local-terraform-code
Can be supplied multiple times: --terragrunt-source-map source1=dest1 --terragrunt-source-map source2=dest2
The --terragrunt-source-map source=dest
param replaces any source
URL (including the source URL of a config pulled
in with dependency
blocks) that has root source
with dest
.
For example:
terragrunt apply --terragrunt-source-map github.com/org/modules.git=/local/path/to/modules
The above would replace terraform { source = "github.com/org/modules.git//xxx" }
with terraform { source = /local/path/to/modules//xxx }
regardless of
whether you were running apply
, or run-all
, or using a dependency
.
NOTE: This setting is ignored if you pass in --terragrunt-source
.
Note that this only performs literal matches on the URL portion. For example, a map key of
ssh://git@github.com/gruntwork-io/terragrunt.git
will only match terragrunt configurations with source source =
"ssh://git@github.com/gruntwork-io/terragrunt.git//xxx"
and not sources of the form source =
"git::ssh://git@github.com/gruntwork-io/terragrunt.git//xxx"
. The latter requires a map key of
git::ssh://git@github.com/gruntwork-io/terragrunt.git
.
CLI Arg: --terragrunt-source-update
Environment Variable: TERRAGRUNT_SOURCE_UPDATE
(set to true
)
When passed in, delete the contents of the temporary folder before downloading OpenTofu/Terraform source code into it.
CLI Arg: --terragrunt-ignore-dependency-errors
Environment Variable: TERRAGRUNT_IGNORE_DEPENDENCY_ERRORS
When passed in, the *-all
commands continue processing components even if a dependency fails
CLI Arg: --terragrunt-iam-role
Environment Variable: TERRAGRUNT_IAM_ROLE
Requires an argument: --terragrunt-iam-role "arn:aws:iam::ACCOUNT_ID:role/ROLE_NAME"
Assume the specified IAM role ARN before running OpenTofu/Terraform or AWS commands. This is a convenient way to use Terragrunt and OpenTofu/Terraform with multiple AWS accounts.
CLI Arg: --terragrunt-iam-assume-role-duration
Environment Variable: TERRAGRUNT_IAM_ASSUME_ROLE_DURATION
Requires an argument: --terragrunt-iam-assume-role-duration 3600
Uses the specified duration as the session duration (in seconds) for the STS session which assumes the role defined in --terragrunt-iam-role
.
CLI Arg: --terragrunt-iam-assume-role-session-name
Environment Variable: TERRAGRUNT_IAM_ASSUME_ROLE_SESSION_NAME
Requires an argument: --terragrunt-iam-assume-role-session-name "terragrunt-iam-role-session-name"
Used as the session name for the STS session which assumes the role defined in --terragrunt-iam-role
.
CLI Arg: --terragrunt-iam-web-identity-token
Environment Variable: TERRAGRUNT_IAM_ASSUME_ROLE_WEB_IDENTITY_TOKEN
Requires an argument: --terragrunt-iam-web-identity-token [/path/to/web-identity-token | web-identity-token-value]
Used as the web identity token for assuming a role temporarily using the AWS Security Token Service (STS) with the AssumeRoleWithWebIdentity API.
CLI Arg: --terragrunt-excludes-file
Environment Variable: TERRAGRUNT_EXCLUDES_FILE
Requires an argument: --terragrunt-excludes-file /path/to/file
Path to a file with a list of directories that need to be excluded when running *-all commands, by default .terragrunt-excludes
. Modules under these directories will be
excluded during execution of the commands. If a relative path is specified, it should be relative from
–terragrunt-working-dir. This will only exclude the module, not its dependencies.
This flag has been designed to integrate nicely with the hclvalidate
command, which can return a list of invalid files delimited by newlines when passed the --terragrunt-hclvalidate-show-config-path
flag. To integrate the two, you can run something like the following using bash process substitution:
terragrunt run-all plan --terragrunt-excludes-file <(terragrunt hclvalidate --terragrunt-hclvalidate-show-config-path)
CLI Arg: --terragrunt-exclude-dir
Environment Variable: TERRAGRUNT_EXCLUDE_DIR
Requires an argument: --terragrunt-exclude-dir /path/to/dirs/to/exclude*
Can be supplied multiple times: --terragrunt-exclude-dir /path/to/dirs/to/exclude --terragrunt-exclude-dir /another/path/to/dirs/to/exclude
Unix-style glob of directories to exclude when running *-all
commands. Modules under these directories will be
excluded during execution of the commands. If a relative path is specified, it should be relative from
–terragrunt-working-dir. Flag can be specified multiple times. This will only exclude the
module, not its dependencies.
Please note that the glob curly braces expansion is not taken in account using environment variable unlike of its equivalent as a parameter on the command line.
You should consider using TERRAGRUNT_EXCLUDE_DIR="foo/module,bar/module"
instead of TERRAGRUNT_EXCLUDE_DIR="{foo,bar}/module"
.
CLI Arg: --terragrunt-include-dir
Environment Variable: TERRAGRUNT_INCLUDE_DIR
Requires an argument: --terragrunt-include-dir /path/to/dirs/to/include*
Can be supplied multiple times: --terragrunt-include-dir /path/to/dirs/to/include --terragrunt-include-dir /another/path/to/dirs/to/include
Unix-style glob of directories to include when running *-all
commands. Only modules under these directories (and all
dependent modules) will be included during execution of the commands. If a relative path is specified, it should be
relative from --terragrunt-working-dir
. Flag can be specified multiple times.
Please note that the glob curly braces expansion is not taken in account using environment variable unlike of its equivalent as a parameter on the command line.
You should consider using TERRAGRUNT_INCLUDE_DIR="foo/module,bar/module"
instead of TERRAGRUNT_INCLUDE_DIR="{foo,bar}/module"
.
CLI Arg: --terragrunt-strict-include
Environment Variable: TERRAGRUNT_STRICT_INCLUDE
When passed in, only modules under the directories passed in with –terragrunt-include-dir will be included. All dependencies of the included directories will be excluded if they are not in the included directories. If no –terragrunt-include-dir flags are included, terragrunt will not include any modules during the execution of the commands.
CLI Arg: --terragrunt-strict-validate
When passed in, and running terragrunt validate-inputs
, enables strict mode for the validate-inputs
command. When strict mode is enabled, an error will be returned if any variables required by the underlying OpenTofu/Terraform configuration are not passed in, OR if any unused variables are passed in. By default, terragrunt validate-inputs
runs in relaxed mode. In relaxed mode, an error is only returned when a variable required by the underlying OpenTofu/Terraform configuration is not passed in.
CLI Arg: --terragrunt-ignore-dependency-order
Environment Variable: TERRAGRUNT_IGNORE_DEPENDENCY_ORDER
When passed in, ignore the dependencies between modules when running *-all
commands.
CLI Arg: --terragrunt-ignore-external-dependencies
Environment Variable: TERRAGRUNT_IGNORE_EXTERNAL_DEPENDENCIES
When passed in, don’t attempt to include any external dependencies when running *-all
commands. Note that an external
dependency is a dependency that is outside the current terragrunt working directory, and is not respective to the
included directories with terragrunt-include-dir
.
CLI Arg: --terragrunt-include-external-dependencies
Environment Variable: TERRAGRUNT_INCLUDE_EXTERNAL_DEPENDENCIES
When passed in, include any external dependencies when running *-all
without asking. Note that an external
dependency is a dependency that is outside the current terragrunt working directory, and is not respective to the
included directories with terragrunt-include-dir
.
CLI Arg: --terragrunt-parallelism
Environment Variable: TERRAGRUNT_PARALLELISM
When passed in, limit the number of modules that are run concurrently to this number during *-all commands.
The exception is the terraform init
command, which is always executed sequentially if the terraform plugin cache is used. This is because the terraform plugin cache is not guaranteed to be concurrency safe.
CLI Arg: --terragrunt-debug
Environment Variable: TERRAGRUNT_DEBUG
When passed in, Terragrunt will create a tfvars file that can be used to invoke the terraform module in the same way that Terragrunt invokes the module, so that you can debug issues with the terragrunt config. See Debugging for some additional details.
CLI Arg: --terragrunt-log-level
Environment Variable: TERRAGRUNT_LOG_LEVEL
Requires an argument: --terragrunt-log-level <LOG_LEVEL>
When passed it, sets logging level for terragrunt. All supported levels are:
stderr
stdout
error
warn
info
(this is the default)debug
trace
Where the first two control the logging of Terraform/OpenTofu output.
CLI Arg: --terragrunt-log-format
Environment Variable: TERRAGRUNT_LOG_FORMAT
Requires an argument: --terragrunt-log-format <LOG_FORMAT>
There are four log format presets:
pretty
(this is the default)bare
(old Terragrunt logging, pre-v0.67.0)json
key-value
CLI Arg: --terragrunt-log-custom-format
Environment Variable: TERRAGRUNT_LOG_CUSTOM_FORMAT
Requires an argument: --terragrunt-log-custom-format <LOG_CUSTOM_FORMAT>
This allows you to customize logging however you like.
Make sure to read Custom Log Format for syntax details.
CLI Arg: --terragrunt-log-disable
Environment Variable: TERRAGRUNT_LOG_DISABLE
Disable logging. This flag also enables terragrunt-forward-tf-stdout.
CLI Arg: --terragrunt-log-show-abs-paths
Environment Variable: TERRAGRUNT_LOG_SHOW_ABS_PATHS
If specified, Terragrunt paths in logs will be absolute. By default, the paths are relative to the working directory.
CLI Arg: --terragrunt-no-color
Environment Variable: TERRAGRUNT_NO_COLOR
If specified, Terragrunt output won’t contain any color.
NOTE: This option does not disable OpenTofu/Terraform output colors. Use the OpenTofu/Terraform -no-color
argument.
CLI Arg: --terragrunt-check
Environment Variable: TERRAGRUNT_CHECK
(set to true
)
Commands:
When passed in, run hclfmt
in check only mode instead of actively overwriting the files. This will cause the
command to exit with exit code 1 if there are any files that are not formatted.
CLI Arg: --terragrunt-diff
Environment Variable: TERRAGRUNT_DIFF
(set to true
)
Commands:
When passed in, running hclfmt
will print diff between original and modified file versions.
CLI Arg: --terragrunt-hclfmt-file
Requires an argument: --terragrunt-hclfmt-file /path/to/terragrunt.hcl
Commands:
When passed in, run hclfmt
only on the specified file.
CLI Arg: --terragrunt-hclfmt-exclude-dir .dir-name
Environment Variable: TERRAGRUNT_HCLFMT_EXCLUDE_DIR
Commands:
Can be supplied multiple times: --terragrunt-hclfmt-exclude-dir .back --terragrunt-hclfmt-exclude-dir .archive
When passed in, hclfmt
will ignore files in the specified directories.
CLI Arg: --terragrunt-hclfmt-stdin
Environment Variable: TERRAGRUNT_HCLFMT_STDIN
(set to true
)
Commands:
When passed in, run hclfmt
only on hcl passed to stdin
, result is printed to stdout
.
CLI Arg: --terragrunt-hclvalidate-json
Environment Variable: TERRAGRUNT_HCLVALIDATE_JSON
(set to true
)
Commands:
When passed in, render the output in the JSON format.
CLI Arg: --terragrunt-hclvalidate-show-config-path
Environment Variable: TERRAGRUNT_HCLVALIDATE_INVALID
(set to true
)
Commands:
When passed in, output a list of files with invalid configuration.
CLI Arg: --terragrunt-override-attr
Requires an argument: --terragrunt-override-attr ATTR=VALUE
Override the attribute named ATTR
with the value VALUE
in a provider
block as part of the aws-provider-patch
command. May be specified multiple times. Also, ATTR
can specify attributes within a nested
block by specifying <BLOCK>.<ATTR>
, where <BLOCK>
is the block name: e.g., assume_role.role
arn will override the
role_arn
attribute of the assume_role { ... }
block.
CLI Arg: --terragrunt-json-out
Requires an argument: --terragrunt-json-out /path/to/terragrunt_rendered.json
Commands:
When passed in, render the json representation in this file.
CLI Arg: --terragrunt-json-disable-dependent-modules
Requires an argument: --terragrunt-json-disable-dependent-modules
Commands:
When the --terragrunt-json-disable-dependent-modules
flag is included in the command, the process of identifying dependent modules will be disabled during JSON rendering.
This lead to a faster rendering process, but the output will not include any dependent modules.
CLI Arg: --terragrunt-modules-that-include
Environment Variable: TERRAGRUNT_MODULES_THAT_INCLUDE
Requires an argument: --terragrunt-modules-that-include /path/to/included-terragrunt.hcl
Commands:
When passed in, run-all
will only run the command against Terragrunt modules that include the specified file.
This applies to the set of modules that are identified based on all the existing criteria for deciding which modules to include. For example, consider the following folder structure:
.
├── _envcommon
│ └── data-stores
│ └── aurora.hcl
├── dev
│ └── us-west-2
│ └── dev
│ ├── data-stores
│ │ └── aurora
│ │ └── terragrunt.hcl
│ └── networking
│ └── vpc
│ └── terragrunt.hcl
└── stage
└── us-west-2
└── stage
├── data-stores
│ └── aurora
│ └── terragrunt.hcl
└── networking
└── vpc
└── terragrunt.hcl
Suppose that both dev/us-west-2/dev/data-stores/aurora/terragrunt.hcl
and
stage/us-west-2/stage/data-stores/aurora/terragrunt.hcl
had the following contents:
include "envcommon" {
path = "../../../../../_envcommon/data-stores/aurora.hcl"
}
If you run the command run-all init --terragrunt-modules-that-include ../_envcommon/data-stores/aurora.hcl
from the
dev
folder, only dev/us-west-2/dev/data-stores/aurora
will be run; not stage/us-west-2/stage/data-stores/aurora
.
This is because run-all
by default restricts the modules to only those that are direct descendents of the current
folder you are running from. If you also pass in --terragrunt-include-dir ../stage
, then it will now include
stage/us-west-2/stage/data-stores/aurora
because now the stage
folder is in consideration.
In other words, Terragrunt will always first find all the modules that should be included before applying this filter, and then will apply this filter on the set of modules that it found.
You can pass this argument in multiple times to provide a list of include files to consider. When multiple files are passed in, the set will be the union of modules that includes at least one of the files in the list.
NOTE: When using relative paths, the paths are relative to the working directory. This is either the current working directory, or any path passed in to terragrunt-working-dir.
TIP: This flag is functionally covered by the --terragrunt-queue-include-units-reading
flag, but is more explicitly
only for the include
configuration block.
CLI Arg: --terragrunt-queue-include-units-reading
Environment Variable: TERRAGRUNT_QUEUE_INCLUDE_UNITS_READING
Commands:
This flag works very similarly to the --terragrunt-modules-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
commands 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:
.
├── reading-shared-hcl
│ └── terragrunt.hcl
├── also-reading-shared-hcl
│ └── terragrunt.hcl
├── not-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:
locals {
shared = read_terragrunt_config(find_in_parent_folders("shared.hcl"))
}
If you run the command run-all init --terragrunt-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:
locals {
filename = mark_as_read("file-read-by-tofu.txt")
}
inputs = {
filename = local.filename
}
⚠️: Due to the way that Terragrunt parses configurations during a 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 been populated with units to run.
CLI Arg: --terragrunt-fetch-dependency-output-from-state
Environment Variable: TERRAGRUNT_FETCH_DEPENDENCY_OUTPUT_FROM_STATE
(set to true
)
When using many dependencies, this option can speed up the dependency processing by fetching dependency output directly from the state file instead of init dependencies and running terraform on them. NOTE: This is an experimental feature, use with caution. Currently only AWS S3 backend is supported.
CLI Arg: --terragrunt-use-partial-parse-config-cache
Environment Variable: TERRAGRUNT_USE_PARTIAL_PARSE_CONFIG_CACHE
(set to true
)
This flag can be used to drastically decrease time required for parsing Terragrunt files. The effect will only show if a lot of similar includes are expected such as the root terragrunt.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:
run-all
command where only the dependency
blocks need to be evaluated to determine run order.terraform
block to determine state configurations for fetching dependency
outputs.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.
DEPRECATED: Since this behavior has become by default, this flag has been removed. In order to get raw Terraform/OpenTofu output, use terragrunt-forward-tf-stdout.
CLI Arg: --terragrunt-include-module-prefix
Environment Variable: TERRAGRUNT_INCLUDE_MODULE_PREFIX
(set to true
)
When this flag is set output from OpenTofu/Terraform sub-commands is prefixed with module path.
CLI Arg: --terragrunt-fail-on-state-bucket-creation
Environment Variable: TERRAGRUNT_FAIL_ON_STATE_BUCKET_CREATION
(set to true
)
When this flag is set, Terragrunt will fail and exit if it is necessary to create the remote state bucket.
CLI Arg: --terragrunt-disable-bucket-update
Environment Variable: TERRAGRUNT_DISABLE_BUCKET_UPDATE
(set to true
)
When this flag is set, Terragrunt does not update the remote state bucket, which is useful to set if the state bucket is managed by a third party.
CLI Arg: --terragrunt-disable-command-validation
Environment Variable: TERRAGRUNT_DISABLE_COMMAND_VALIDATION
(set to true
)
When this flag is set, Terragrunt will not validate the terraform command, which can be useful when need to use non-existent commands in hooks.
DEPRECATED: Use terragrunt-log-format.
CLI Arg: --terragrunt-json-log
Environment Variable: TERRAGRUNT_JSON_LOG
(set to true
)
When this flag is set, Terragrunt will output its logs in JSON format.
DEPRECATED: Use terragrunt-log-format. OpenTofu/Terraform stdout
and stderr
is wrapped in JSON by default with --terragurnt-log-format json
flag if --terragrunt-forward-tf-stdout
flag is not specified.
In other words, the previous behavior with the --terragrunt-json-log --terragrunt-tf-logs-to-json
flags is now equivalent to --terragrunt-log-format json
and the previous behavior with the --terragrunt-json-log
is now equivalent to --terragrunt-log-format json --terragrunt-forward-tf-stdout
.
CLI Arg: --terragrunt-tf-logs-to-json
Environment Variable: TERRAGRUNT_TF_JSON_LOG
(set to true
)
When this flag is set, Terragrunt will wrap OpenTofu/Terraform stdout
and stderr
in JSON log messages. Works only with --terragrunt-json-log
flag.
CLI Arg: --terragrunt-provider-cache
Environment Variable: TERRAGRUNT_PROVIDER_CACHE
Commands:
Enables Terragrunt’s provider caching. This forces OpenTofu/Terraform to make provider requests through the Terragrunt Provider Cache server. Make sure to read Provider Caching for context.
CLI Arg: --terragrunt-provider-cache-dir
Environment Variable: TERRAGRUNT_PROVIDER_CACHE_DIR
Commands:
The path to the Terragrunt provider cache directory. By default, terragrunt/providers
folder in the user cache directory: $HOME/.cache
on Unix systems, $HOME/Library/Caches
on Darwin, %LocalAppData%
on Windows. The file structure of the cache directory is identical to the OpenTofu/Terraform plugin_cache_dir directory. Make sure to read Provider Caching for context.
CLI Arg: --terragrunt-provider-cache-hostname
Environment Variable: TERRAGRUNT_PROVIDER_CACHE_HOSTNAME
Commands:
The hostname of the Terragrunt Provider Cache server. By default, ‘localhost’. Make sure to read Provider Caching for context.
CLI Arg: --terragrunt-provider-cache-port
Environment Variable: TERRAGRUNT_PROVIDER_CACHE_PORT
Commands:
The port of the Terragrunt Provider Cache server. By default, assigned automatically. Make sure to read Provider Caching for context.
CLI Arg: --terragrunt-provider-cache-token
Environment Variable: TERRAGRUNT_PROVIDER_CACHE_TOKEN
Commands:
The Token for authentication on the Terragrunt Provider Cache server. By default, assigned automatically. Make sure to read Provider Caching for context.
CLI Arg: --terragrunt-provider-cache-registry-names
Environment Variable: TERRAGRUNT_PROVIDER_CACHE_REGISTRY_NAMES
Commands:
The list of remote registries to cached by Terragrunt Provider Cache server. By default, ‘registry.terraform.io’, ‘registry.opentofu.org’. Make sure to read Provider Caching for context.
CLI Arg: --terragrunt-out-dir
Environment Variable: TERRAGRUNT_OUT_DIR
Commands:
Specify the plan output directory for the *-all
commands. Useful to save plans between runs in a single place.
CLI Arg: --terragrunt-json-out-dir
Environment Variable: TERRAGRUNT_JSON_OUT_DIR
Commands:
Specify the output directory for the *-all
commands to store plans in JSON format. Useful to read plans programmatically.
CLI Arg: --terragrunt-auth-provider-cmd
Environment Variable: TERRAGRUNT_AUTH_PROVIDER_CMD
Requires an argument: --terragrunt-auth-provider-cmd "command [arguments]"
The command and arguments used to obtain authentication credentials dynamically. If specified, Terragrunt runs this command for every working directory before running the underlying IAC for a terragrunt.hcl
file.
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 terragrunt-auth-provider-cmd
results in JSON matching the schema above, corresponding environment variables will be set before Terragrunt begins IAC execution for a terragrunt.hcl
file.
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 you’d like, however, as long as Terragrunt can execute it. The expected pattern for using this flag is to populate the values dynamically using a secret store, etc.
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.
DEPRECATED: Use terragrunt-log-format.
CLI Arg: --terragrunt-disable-log-formatting
Environment Variable: TERRAGRUNT_DISABLE_LOG_FORMATTING
If specified, logs will be displayed in key/value format. By default, logs are formatted in a human readable format.
The example of what the log looks like without the --terragrunt-disable-log-formatting
flag specified:
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:
The example of what the log looks like with the --terragrunt-forward-tf-stdout
flag specified:
time=2024-08-23T11:47:18+03:00 level=info prefix=app msg=Running command: tofu plan -input=false
time=2024-08-23T11:47:18+03:00 level=stdout prefix=app binary=tofu msg=OpenTofu used the selected providers to generate the following execution
time=2024-08-23T11:47:18+03:00 level=stdout prefix=app binary=tofu msg=plan. Resource actions are indicated with the following symbols:
time=2024-08-23T11:47:18+03:00 level=stdout prefix=app binary=tofu msg= + create
time=2024-08-23T11:47:18+03:00 level=stdout prefix=app binary=tofu msg=OpenTofu will perform the following actions:
CLI Arg: --terragrunt-forward-tf-stdout
Environment Variable: TERRAGRUNT_FORWARD_TF_STDOUT
If specified, the output of Terraform/OpenTofu commands will be printed as is. By default, all logs, except when using the output
command or -json
flags, are integrated into the Terragrunt log.
The example of what the log looks like without the --terragrunt-forward-tf-stdout
flag specified:
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:
The example of what the log looks like with the --terragrunt-forward-tf-stdout
flag specified:
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:
CLI Arg: --terragrunt-no-destroy-dependencies-check
Environment Variable: TERRAGRUNT_NO_DESTROY_DEPENDENCIES_CHECK
If specified, Terragrunt will not check dependent modules when running destroy
command. By default, Terragrunt checks dependent modules when running destroy
command.
CLI Arg: --feature
Environment Variable: TERRAGRUNT_FEATURE
Feature flags in Terragrunt allow users to dynamically control configuration behavior through CLI arguments or environment variables.
These flags enable a more flexible and controlled deployment process, particularly in monorepo contexts with interdependent infrastructure units.
Example HCL flags definition:
feature "string_feature_flag" {
default = "test"
}
feature "int_feature_flag" {
default = 777
}
feature "bool_feature_flag" {
default = false
}
terraform {
before_hook "conditional_command" {
commands = ["apply", "plan", "destroy"]
execute = feature.bool_feature_flag.value ? ["sh", "-c", "echo running conditional bool_feature_flag"] : [ "sh", "-c", "exit", "0" ]
}
}
inputs = {
string_feature_flag = feature.string_feature_flag.value
int_feature_flag = feature.int_feature_flag.value
}
Setting a feature flag through the CLI:
terragrunt --feature int_feature_flag=123 --feature bool_feature_flag=true --feature string_feature_flag=app1 apply
Setting feature flags through environment variables:
export TERRAGRUNT_FEATURE=int_feature_flag=123,bool_feature_flag=true,string_feature_flag=app1
terragrunt apply