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"
}
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 a terraform variable in the corresponding module) and undefined required inputs (required 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 terraform are not checked by this command.
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 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. 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 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:
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 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 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:
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-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 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-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-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. If no –terragrunt-include-dir flags are included, terragrunt will not include any modules during the execution of the commands.
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
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.
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
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 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.
Install
