This page documents the CLI commands and options available with Terragrunt:
Terragrunt supports the following CLI commands:
Terragrunt is a thin wrapper for Terraform, so except for a few of the special commands defined in these docs,
Terragrunt forwards all other commands to Terraform. For example, when you run terragrunt apply
, Terragrunt executes
terraform apply
.
Examples:
terragrunt plan
terragrunt apply
terragrunt output
terragrunt destroy
# etc
Run terraform --help
to get the full list.
Runs the provided terraform command against a ‘stack’, where a ‘stack’ is a tree of terragrunt modules. The command will recursively find terragrunt modules in the current directory tree and run the 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 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 modules and run
apply
in each one, concurrently, while respecting ordering defined via
dependency
and
dependencies
blocks.
[WARNING] Using run-all
with 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 plan-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 plan
instead.
Display the plans of a ‘stack’ by running ‘terragrunt plan’ in each subfolder. Make sure to read Execute Terraform commands on multiple modules at once for context.
Example:
terragrunt plan-all
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] plan-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 plan-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 apply
instead.
Apply a ‘stack’ by running ‘terragrunt apply’ in each subfolder. Make sure to read Execute 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.
DEPRECATED: Use run-all output
instead.
Display the outputs of a ‘stack’ by running ‘terragrunt output’ in each subfolder. Make sure to read Execute 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 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.
DEPRECATED: Use run-all validate
instead.
Validate ‘stack’ by running ‘terragrunt validate’ in each subfolder. Make sure to read Execute 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"
}
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 terragrunt.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
(terragrunt.hcl
) and run the equivalent of terraform fmt
on them.
Overwrite settings on nested AWS providers to work around several Terraform bugs. Due to
issue #13018 and
issue #26211, the import
command may fail if your 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. 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
assume_role {
role_arn = var.role_arn
}
}
Both the region
and role_arn
parameters are set to dynamic values, which will trigger those Terraform bugs. To work
around it, run the following command:
terragrunt aws-provider-patch \
--terragrunt-override-attr region=eu-west-1 \
--terragrunt-override-attr assume_role.role_arn=""
When you run the command above, Terragrunt will:
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 ""
.The result will look like this:
provider "aws" {
region = "eu-west-1"
assume_role {
role_arn = ""
}
}
This should allow you to run import
on the module and work around those Terraform bugs. When you’re done running
import
, remember to delete your overridden code! E.g., Delete the .terraform
or .terragrunt-cache
folders.
Terragrunt forwards all options to 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 apply-all
, destroy-all
, output-all
, validate-all
, and
plan-all
commands.
CLI Arg: --terragrunt-tfpath
Environment Variable: TERRAGRUNT_TFPATH
Requires an argument: --terragrunt-tfpath /path/to/terraform-binary
A custom path to the Terraform binary. The default is terraform
in a directory on your PATH.
CLI Arg: --terragrunt-no-auto-init
Environment Variable: TERRAGRUNT_AUTO_INIT
(set to false
)
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-retry
Environment Variable: TERRAGRUNT_AUTO_RETRY
(set to false
)
When passed in, don’t automatically retry commands which fail with transient errors. See Auto-Retry
CLI Arg: --terragrunt-non-interactive
Environment Variable: TF_INPUT
(set to false
)
When passed in, don’t show interactive user prompts. This will default the answer for all prompts to ‘yes’. 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.
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 apply-all
, destroy-all
, output-all
, validate-all
, and plan-all
commands, this parameter has
a different meaning: Terragrunt will apply or destroy all the 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 Terraform code when using remote 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 Terraform configurations from the specified source into a temporary folder, and run Terraform in that temporary
folder. The source should use the same syntax as the Terraform module
source parameter. If you specify this argument for the apply-all
,
destroy-all
, output-all
, validate-all
, or plan-all
commands, Terragrunt will assume this is the local file path
for all of your Terraform modules, and for each module processed by the xxx-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-update
Environment Variable: TERRAGRUNT_SOURCE_UPDATE
(set to true
)
When passed in, delete the contents of the temporary folder before downloading Terraform source code into it.
CLI Arg: --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 Terraform or AWS commands. This is a convenient way to use Terragrunt and Terraform with multiple AWS accounts.
CLI Arg: --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.
CLI Arg: --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.
CLI Arg: --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.
CLI Arg: --terragrunt-ignore-dependency-order
When passed in, ignore the depedencies between modules when running *-all
commands.
CLI Arg: --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
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.
CLI Arg: --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
Requires an argument: --terragrunt-log-level <LOG_LEVEL>
When passed it, sets logging level for terragrunt. All supported levels are:
CLI Arg: --terragrunt-check
Environment Variable: TERRAGRUNT_CHECK
(set to true
)
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-hclfmt-file
Requires an argument: --terragrunt-hclfmt-file /path/to/terragrunt.hcl
When passed in, run hclfmt
only on specified */terragrunt.hcl
file.
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.