Shape
Shape

This page documents the CLI commands and options available with Terragrunt:

CLI commands

Terragrunt supports the following CLI commands:

All Terraform built-in 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.

plan-all

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.

apply-all

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.

output-all

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.

destroy-all

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.

validate-all

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.

terragrunt-info

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

graph-dependencies

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";
}

hclfmt

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.

aws-provider-patch

Overwrite settings on nested AWS providers to work around a Terraform bug. Due to issue #13018, 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, based on the terragrunt-override-attr options you set, so that import can work.

Example:

terragrunt aws-provider-patch --terragrunt-override-attr region=eu-west-1

When you run the command above, Terragrunt will:

  1. Run terraform init to download the code for all your modules into .terraform/modules.
  2. Scan all the Terraform code in .terraform/modules, find AWS provider blocks, and hard-code the region param to eu-west-1 for each one.

This should allow you to run import on the module and work around issue #13018.

CLI options

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:

terragrunt-config

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.

terragrunt-tfpath

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.

terragrunt-no-auto-init

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

terragrunt-no-auto-retry

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

terragrunt-non-interactive

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.

terragrunt-working-dir

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.

terragrunt-download-dir

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.

terragrunt-source

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.

terragrunt-source-update

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.

terragrunt-ignore-dependency-errors

CLI Arg: --terragrunt-ignore-dependency-errors

When passed in, the *-all commands continue processing components even if a dependency fails

terragrunt-iam-role

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.

terragrunt-exclude-dir

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.

terragrunt-include-dir

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.

terragrunt-strict-include

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.

terragrunt-ignore-dependency-order

CLI Arg: --terragrunt-ignore-dependency-order

When passed in, ignore the depedencies between modules when running *-all commands.

terragrunt-ignore-external-dependencies

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.

terragrunt-include-external-dependencies

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.

terragrunt-parallelism

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.

terragrunt-debug

CLI Arg: --terragrunt-debug

When passed in, run Terragrunt in debug mode where the vars that are passed into Terragrunt are recorded as a tfvars.json file.

terragrunt-check

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.

terragrunt-hclfmt-file

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.

terragrunt-override-attr

CLI Arg: --terragrunt-override-attr Requires an argument: --terragrunt-override-attr KEY=VALUE

A KEY=VALUE attribute to override in a provider block as part of the aws-provider-patch command. May be specified multiple times.