exec

Usage

Execute an arbitrary command, wrapped by Terragrunt.

Examples

Execute 'echo "Hello, Terragrunt!"' via Terragrunt.

terragrunt exec -- echo "Hello, Terragrunt!"

Inspect `main.tf` file of module for Unit

terragrunt exec --in-download-dir -- cat main.tf

Difference between run and exec

In contrast to the run command, which will always invoke OpenTofu/Terraform, the exec command allows for execution of any arbitrary command via Terragrunt.

This can be useful, as it allows you full control over the process that is being orchestrated by Terragrunt, while taking advantage of Terragrunt’s features such as dependency resolution, inputs, and more.

Interaction with configuration

When using exec, you will have almost the exact same configuration context that you have when using run, including inputs.

terragrunt.hcl

inputs = {
  message = "Hello, Terragrunt!"
}

Running the following command will show that the message input is available to the command:

$ terragrunt exec -- env | grep 'TF_VAR_message'
TF_VAR_message=Hello, Terragrunt!

Flags

--auth-provider-cmd

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

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

The output must be valid JSON of the following schema:

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

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

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

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

#!/usr/bin/env bash

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

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

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

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

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

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

Note

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

Caution

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

Type: string

Environment Variables:

• TG_AUTH_PROVIDER_CMD

--config

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

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

This is useful when you:

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

Example usage:

terragrunt run plan --config custom-config.hcl

Type: string

Environment Variables:

• TG_CONFIG

--download-dir

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

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

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

Note

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

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

Type: string

Environment Variables:

• TG_DOWNLOAD_DIR

--iam-assume-role

Assume the specified IAM role before executing OpenTofu/Terraform.

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

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

Type: string

Environment Variables:

• TG_IAM_ASSUME_ROLE

--iam-assume-role-duration

Session duration for IAM Assume Role session.

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

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

Type: string

Environment Variables:

• TG_IAM_ASSUME_ROLE_DURATION

--iam-assume-role-session-name

Name for the IAM Assumed Role session.

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

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

Type: string

Environment Variables:

• TG_IAM_ASSUME_ROLE_SESSION_NAME

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

For AssumeRoleWithWebIdentity, the WebIdentity token.

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

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

Type: string

Environment Variables:

• TG_IAM_ASSUME_ROLE_WEB_IDENTITY_TOKEN

--in-download-dir

Run the provided command in the download directory.

When enabled, Terragrunt will execute the provided command in the temporary download directory where modules are cached, rather than the current working directory.

This is particularly useful when you need to:

• Inspect downloaded module contents.
• Execute commands against the actual module source code.
• Debug issues with downloaded modules.

Example:

# View the contents of main.tf in the downloaded module
terragrunt exec --in-download-dir -- cat main.tf

# List all files in the downloaded module
terragrunt exec --in-download-dir -- ls -la

Type: bool

Environment Variables:

• TG_IN_DOWNLOAD_DIR

--inputs-debug

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

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

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

Type: bool

Environment Variables:

• TG_INPUTS_DEBUG