# run

> Run OpenTofu/Terraform commands.

## Usage

Run a command, passing arguments to an orchestrated tofu/terraform binary.

This is the explicit, and most flexible form of running an IaC command with Terragrunt. Shortcuts can be found in "terragrunt --help" for common use-cases.

## Examples

Run the plan command.

```bash
terragrunt run plan
# Shortcut:
# terragrunt plan
```

Run the plan command, and pass additional arguments.

```bash
terragrunt run -- output -json
# Shortcut:
# terragrunt output -json
```

## Running multiple units

Note that the `run` command is a more explicit and flexible way to run OpenTofu/Terraform commands in comparison to [OpenTofu shortcuts](/reference/cli/commands/opentofu-shortcuts).

The `run` command also supports the following flags that can be used to drive runs in multiple units:

* `--all`: Run the provided OpenTofu/Terraform command against all units in the current stack.
* `--graph`: Run the provided OpenTofu/Terraform command against the graph of dependencies for the unit in the current working directory.

## Filtering Units

The `run` command supports the `--filter` flag to target specific units using a flexible query language. This is particularly useful when running commands across multiple units with `--all`.

### Running Affected Components

For the common use case of running commands on components affected by changes between the default branch and `HEAD`, you can use the `--filter-affected` flag:

```bash
# Plan changes for affected components
terragrunt run --all --filter-affected -- plan


# Apply changes for affected components
terragrunt run --all --filter-affected -- apply
```

This is equivalent to `terragrunt run --all --filter '[main...HEAD]' -- plan` and automatically detects your repository’s default branch. When using `--filter-affected` with the `run` command, you must use one of the `plan` or `apply` commands, and not the `-destroy` flag.

### Basic Filtering Examples

```bash
# Filter by path with glob patterns
terragrunt run --all --filter 'prod/**' -- plan


# Filter by name
terragrunt run --all --filter 'app*' -- apply


# Filter by type
terragrunt run --all --filter 'type=unit' -- plan
```

### Advanced Filtering

The filter syntax supports negation, intersection, and complex queries:

```bash
# Exclude specific configurations
terragrunt run --all --filter '!./test/**' -- plan


# Combine filters with intersection (refinement)
terragrunt run --all --filter './prod/** | type=unit' -- apply


# Complex queries with chaining
terragrunt run --all --filter './prod/** | type=unit | !name=legacy' -- plan


# Multiple filters (OR logic)
terragrunt run --all --filter 'app1' --filter 'app2' -- plan
```

Learn More About Filtering

For comprehensive examples and advanced usage patterns, see the [Filters feature documentation](/features/filter).

## Separating Arguments

You may, at times, need to explicitly separate the arguments used for Terragrunt from those used for OpenTofu/Terraform. In those circumstances, you can use the argument `--` to separate the Terragrunt flags from the OpenTofu/Terraform flags.

```bash
terragrunt run -- plan -no-color
```

Caution

When using `run --all plan` with units that have dependencies (e.g. via `dependency` or `dependencies` blocks), the command will fail if those dependencies have never been deployed. This is because Terragrunt cannot resolve dependency outputs without existing state.

To work around this issue, use [mock outputs in dependency blocks](/reference/hcl/blocks/#dependency).

Caution

Do not set `TF_PLUGIN_CACHE_DIR` when using `run --all`. This can cause concurrent access issues with the provider cache. Instead, use Terragrunt’s built-in [Provider Cache Server](/features/caching/provider-cache-server/).

We are working with the OpenTofu team to improve this behavior in the future.

Caution

When using `run --all` with `apply` or `destroy`, Terragrunt automatically adds the `-auto-approve` flag due to limitations with shared stdin making individual approvals impossible.

## Flags

### `--all`

Run the specified OpenTofu/Terraform command on the stack of units in the current directory.

When this flag is set, Terragrunt will run the specified OpenTofu/Terraform command against all units in the current stack. This is useful when you want to apply changes across multiple units at once.

For example:

```bash
terragrunt run --all plan
```

This will run the `plan` command against all units in the current stack.

To learn more about how to use this flag, see the [Stacks](/features/stacks) feature documentation.

Note

Terragrunt has a notion of “external dependencies”. These are units that are not part of the current stack, from the perspective of the current working directory, but are dependencies of units that are part of the current stack.

When running an `--all` command, Terragrunt will discover any external dependencies and prompt you to confirm that you want to run them as well.

If you would like to suppress this prompt, you can use the [`--non-interactive` flag](/reference/cli/commands/run#non-interactive). You can also prevent this behavior by setting [`--queue-exclude-external`](/reference/cli/commands/run#queue-exclude-external).

Danger

When running a `run --all destroy` command, Terragrunt will destroy all dependencies of the units under the current working directory, in addition to the units themselves by default!

If you wish to prevent external dependencies from being destroyed, add the [`--queue-exclude-external` flag](/reference/cli/commands/run#queue-exclude-external), or use the [`--exclude-dir` flag](/reference/cli/commands/run#exclude-dir) once for each directory you wish to exclude.

Caution

Use `run --all` with care if you have unapplied dependencies.

If you have a stack of Terragrunt units with dependencies between them via `dependency` blocks and you’ve never deployed them, then commands like `run --all plan` will fail, as it won’t be possible to resolve outputs of `dependency` blocks without applying them first.

The solution for this is to take advantage of [mock outputs in dependency blocks](/reference/hcl/blocks/#dependency).

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](https://opentofu.org/docs/cli/commands/plan/#other-options) 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:

* If any unit throws a 1, Terragrunt will throw a 1.
* If any unit throws a 2, but nothing throws a 1, Terragrunt will throw a 2.
* If nothing throws a non-zero, Terragrunt will throw a 0.

- **Type:** `bool`
- **Environment variables:** `TG_ALL`

### `--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`](/reference/hcl/functions#get_aws_account_id) where authentication has to already have taken place. It can also be useful for HCL functions like [`run_cmd`](/reference/hcl/functions#run_cmd) where it may be useful to be authenticated before calling the function.

The output must be valid JSON of the following schema:

auth-provider-cmd/v2/schema.json

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.terragrunt.com/schemas/auth-provider-cmd/v2/schema.json",
  "title": "Terragrunt Auth Provider Command Response Schema",
  "description": "Schema for the JSON response expected from an auth provider command",
  "type": "object",
  "properties": {
    "awsCredentials": {
      "type": "object",
      "description": "AWS credentials to set as environment variables",
      "properties": {
        "ACCESS_KEY_ID": {
          "type": "string",
          "description": "AWS access key ID"
        },
        "SECRET_ACCESS_KEY": {
          "type": "string",
          "description": "AWS secret access key"
        },
        "SESSION_TOKEN": {
          "type": "string",
          "description": "AWS session token (optional)"
        }
      },
      "required": [
        "ACCESS_KEY_ID",
        "SECRET_ACCESS_KEY"
      ],
      "additionalProperties": false
    },
    "awsRole": {
      "type": "object",
      "description": "AWS role to assume",
      "properties": {
        "roleARN": {
          "type": "string",
          "description": "The ARN of the IAM role to assume"
        },
        "roleSessionName": {
          "type": "string",
          "description": "The session name for the assumed role"
        },
        "duration": {
          "type": "integer",
          "description": "Duration in seconds for the assumed role session",
          "minimum": 0
        },
        "webIdentityToken": {
          "type": "string",
          "description": "Web identity token for OIDC-based role assumption"
        }
      },
      "required": [
        "roleARN"
      ],
      "additionalProperties": false
    },
    "envs": {
      "type": "object",
      "description": "Additional environment variables to set",
      "additionalProperties": {
        "type": "string"
      }
    }
  },
  "additionalProperties": false
}
```

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:

```bash
#!/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:

```bash
terragrunt run plan --config custom-config.hcl
```

- **Type:** `string`
- **Environment variables:** `TG_CONFIG`

### `--json-out-dir`

Directory to store JSON plan files generated from plans via show -json.

Note

This flag only does anything when used with the `--all` flag for stack runs. It does nothing in single-unit runs.

To generate JSON plan files for a single unit run, use the standard OpenTofu/Terraform [-out flag](https://opentofu.org/docs/cli/commands/plan) like so:

```bash
terragrunt run -- plan -out=/tmp/tfplan
```

```bash
terragrunt run -- show -json /tmp/tfplan > /tmp/tfplan.json
```

Generates machine-readable plan outputs per unit as `tfplan.json` by invoking `show -json` after the plan is created.

* Requires a plan to exist (e.g. created with `--out-dir`).
* If the directory does not exist, Terragrunt creates it.
* Relative paths are resolved against the root working directory, and Terragrunt mirrors the unit path under this directory (e.g. `<json-out-dir>/<relative-unit-path>/tfplan.json`).

Examples:

```bash
# Create native plan files and JSON plans for all units
terragrunt run --all --out-dir /tmp/all --json-out-dir /tmp/all plan


# Or store JSON plans separately
terragrunt run --all --out-dir /tmp/plan --json-out-dir /tmp/json plan
```

See the [Stacks](/features/stacks/stack-operations#saving-opentofuterraform-plan-output) docs for more usage examples.

- **Type:** `string`
- **Environment variables:** `TG_JSON_OUT_DIR`

### `--dependency-fetch-output-from-state`

Fetch dependency outputs directly from the state file instead of using `tofu output`.


This flag modifies how Terragrunt retrieves output values from dependent units. When enabled, Terragrunt will read the outputs directly from the state file instead of running `terraform output` or `tofu output`.

Note

This flag is equivalent to enabling the `dependency-fetch-output-from-state` experiment. You can also enable this feature using `--experiment dependency-fetch-output-from-state` or `--experiment-mode`. For more information, see the [Experiments documentation](/reference/experiments/active#dependency-fetch-output-from-state).

The main benefit this flag provides is performance. Reading directly from state is typically faster than executing the OpenTofu/Terraform binary to get the same outputs.

The limitation of this approach is that it is only supported by the S3 backend, and OpenTofu/Terraform may change the schema of the state file in the future, breaking this functionality.

Caution

This flag is **not compatible with OpenTofu state encryption**. When OpenTofu’s client-side state encryption is enabled, the state file stored in S3 is encrypted before upload. Since this flag causes Terragrunt to read the raw state file directly from S3 via the AWS SDK, it cannot decrypt the state and will fail with a JSON parsing error. If you are using OpenTofu state encryption, disable this flag with `--no-dependency-fetch-output-from-state`.

Caution

Avoid using this flag without pinning the version of OpenTofu/Terraform you are using.

There is no guarantee that OpenTofu/Terraform will maintain the existing schema of their state files, so there is also no guarantee that the flag will work as expected in future versions of OpenTofu/Terraform. They have not changed the schema of the state file in a long time, but there is no guarantee that they will not change it in the future. We are coordinating with the OpenTofu team to encourage stability in the state file schema, unless significant performance improvements can be made to OpenTofu output fetching to make this flag unnecessary.

Tip

Direct output fetching is a performance optimization. For more details on performance optimizations, their tradeoffs, and other performance tips, read the dedicated [Performance documentation](/troubleshooting/performance).

- **Type:** `bool`
- **Environment variables:** `TG_DEPENDENCY_FETCH_OUTPUT_FROM_STATE`

### `--disable-bucket-update`

When this flag is set, Terragrunt will not update the remote state resources.


When enabled, Terragrunt will throw an error if it detects that remote state resources need to be updated.

This is useful in scenarios where:

* You want to ensure state bucket configurations remain unchanged during operations
* You have separate processes for managing state bucket configurations

The flag acts as a safety mechanism to prevent unintended modifications to your state storage infrastructure.

- **Type:** `bool`
- **Environment variables:** `TG_DISABLE_BUCKET_UPDATE`

### `--disable-command-validation`

When this flag is set, Terragrunt will not validate the tofu/terraform command.

Caution

**Deprecated**: The `--disable-command-validation` flag is deprecated and will be removed in a future version of Terragrunt. Command validation has been removed entirely from Terragrunt. The `run` command now accepts any command and passes it through to the underlying OpenTofu/Terraform binary without validation. This flag no longer has any effect and can be safely removed from your commands.

To prepare for this change, you can enable the `disable-command-validation` strict control to ensure you’re not using this flag. For more information, see the [Strict Controls documentation](/reference/strict-controls/active#disable-command-validation).

This flag disables Terragrunt’s built-in validation of OpenTofu/Terraform commands. When enabled, Terragrunt will pass commands through to OpenTofu/Terraform without checking if they are valid or supported.

- **Type:** `bool`
- **Environment variables:** `TG_DISABLE_COMMAND_VALIDATION`

### `--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`

### `--out-dir`

Directory to store plan files generated by plan/show and consumed by apply/destroy.

Note

This flag only does anything when used with the `--all` flag for stack runs. It does nothing in single-unit runs.

To generate plan files for a single unit run, use the standard OpenTofu/Terraform [-out flag](https://opentofu.org/docs/cli/commands/plan) like so:

```bash
terragrunt run -- plan -out=/tmp/tfplan
```

Specifies where Terragrunt writes native OpenTofu/Terraform plan files for each unit when running stack operations.

* Plans are written as `tfplan.tfplan` per unit.
* If the directory does not exist, Terragrunt creates it.
* Relative paths are resolved against the root working directory, and Terragrunt mirrors the unit path under this directory (e.g. `<out-dir>/<relative-unit-path>/tfplan.tfplan`).

Caution

`--out-dir` controls **where** Terragrunt reads and writes per-unit plan files, but it does **not** restrict which units `run --all apply` discovers. If your plan was scoped with `--filter`, you must reuse the same `--filter` on `apply` — otherwise Terragrunt will discover unfiltered units, fail to find their plan files in `--out-dir`, and error out.

See [Saving OpenTofu/Terraform plan output](https://docs.terragrunt.com/features/stacks/stack-operations/#saving-opentofuterraform-plan-output) for the full plan-then-apply pattern.

Examples:

```bash
# Save plans for all units under /tmp/tfplan
terragrunt run --all plan --out-dir /tmp/tfplan


# Apply using the previously generated plans (per-unit paths are inferred)
terragrunt run --all apply --out-dir /tmp/tfplan
```

See the [Stacks](/features/stacks/stack-operations#saving-opentofuterraform-plan-output) docs for more usage examples.

- **Type:** `string`
- **Environment variables:** `TG_OUT_DIR`

### `--engine-cache-path`

Cache path for Terragrunt engine files.

Specifies the directory where Terragrunt will store its engine cache files. The engine cache helps improve performance by storing compiled configurations and other internal data.

When not specified, Terragrunt will use a default location in the system’s temporary directory.

You must also set the [`experimental-engine`](/reference/cli/commands/run#experimental-engine) flag to enable engine usage.

- **Type:** `string`
- **Environment variables:** `TG_ENGINE_CACHE_PATH`

### `--engine-log-level`

Terragrunt engine log level.

Controls the verbosity of logs from the Terragrunt engine. This is separate from the main Terragrunt logging and specifically affects engine-related operations like configuration parsing and dependency resolution.

By default, the engine log level is set to that of the main Terragrunt logging level.

You must also set the [`experimental-engine`](/reference/cli/commands/run#experimental-engine) flag to enable engine usage.

- **Type:** `string`
- **Environment variables:** `TG_ENGINE_LOG_LEVEL`

### `--engine-skip-check`

Skip checksum check for Terragrunt engine files.

When enabled, Terragrunt will skip the checksum validation of engine files.

This can be useful during development or testing, and is currently the only way to use self-developed engines.

Terragrunt currently only has support for verifying the signatures of official engines, though this will change in the future.

In the meantime, you are encouraged to download engines from a trusted source, verify the integrity of the engine manually, and then reference the local path to the engine in your Terragrunt configuration.

You must also set the [`experimental-engine`](/reference/cli/commands/run#experimental-engine) flag to use engines.

- **Type:** `bool`
- **Environment variables:** `TG_ENGINE_SKIP_CHECK`

### `--experimental-engine`

Enable Terragrunt experimental engine.

Enables the `iac-engine` experiment to use [Terragrunt IaC engines](/features/units/engine).

This flag is equivalent to using `--experiment iac-engine`. You can also enable this experiment using the environment variable `TG_EXPERIMENT=iac-engine`.

IaC engines are still experimental, as the API is unstable and may change in future minor versions of Terragrunt.

If you are using a remote custom engine, you must also set the [`engine-skip-check`](/reference/cli/commands/run#engine-skip-check) flag to skip the signature check for the engine.

- **Type:** `bool`
- **Environment variables:** `TG_EXPERIMENTAL_ENGINE`

### `--feature`

Set feature flags for the HCL code.

Allows enabling or disabling specific features in the HCL code.

To learn more about feature flags, see the [Feature Flags](/features/units/runtime-control#feature-flags) feature documentation.

- **Type:** `string`
- **Environment variables:** `TG_FEATURE`

### `--filter`

Filter configurations using a flexible query language

The `--filter` flag provides a sophisticated querying syntax for targeting specific [units](/features/units) and [stacks](/features/stacks) in Terragrunt commands.

## Usage

```bash
terragrunt find --filter 'app*'
terragrunt list --filter './prod/** | type=unit'
terragrunt run --all --filter './prod/**' -- plan
terragrunt hcl fmt --filter './prod/**'
terragrunt hcl validate --filter 'type=unit'
```

### Name-Based Filtering

Match configurations by their name using exact matches or glob patterns:

```bash
# Exact match
terragrunt find --filter app1


# Glob pattern
terragrunt find --filter 'app*'
```

### Path-Based Filtering

Match configurations by their file system path:

```bash
# Relative paths with globs
terragrunt find --filter './envs/prod/**'


# Absolute paths
terragrunt find --filter '/absolute/path/to/envs/dev/apps/*'
```

### Attribute-Based Filtering

Match configurations by their configuration attributes:

```bash
# Filter by type
terragrunt find --filter 'type=unit'
terragrunt find --filter 'type=stack'


# Filter by external dependency status
terragrunt find --filter 'external=false'


# Filter by files read
terragrunt find --filter 'reading=shared.hcl'
terragrunt find --filter 'reading=common/*.hcl' # Globs supported!
terragrunt find --filter 'reading=config/**' # Double-wildcard globs are required filtering on files nested in subdirectories.
terragrunt find --filter 'reading=config/vars.tfvars'
```

What does 'Reading' mean?

The `reading` attribute filters configurations based on which files they themselves read. This is useful for finding all infrastructure that could potentially be impacted by shared configuration, and is particularly useful when a commonly included configuration (like `root.hcl`) is updated.

See the [mark\_as\_read function documentation](/reference/hcl/functions/#mark_as_read) for more information on how Terragrunt tracks files that are read during parsing.

### Negation

Exclude configurations using the `!` prefix:

```bash
# Exclude by name
terragrunt find --filter '!app1'


# Exclude by path
terragrunt find --filter '!./prod/**'
```

### Intersection (Refinement)

Use the `|` operator to refine results:

```bash
# Find all units in prod directory
terragrunt find --filter './prod/** | type=unit'


# Chain multiple filters
terragrunt find --filter './dev/** | type=unit | !name=unit1'
```

### Git-Based Filtering

Filter configurations based on changes between Git references. For the common use case of comparing the default branch with `HEAD`, you can use the `--filter-affected` flag as a convenient shorthand:

```bash
# Find components affected by changes between main and HEAD
terragrunt find --filter-affected
```

For more control, use Git-based filter expressions directly:

```bash
# Compare between two references
terragrunt find --filter '[main...HEAD]'


# Shorthand: compare reference to HEAD
terragrunt find --filter '[main]'


# Compare between specific commits
terragrunt find --filter '[abc123...def456]'
```

For more details and examples, see the [Filters feature documentation](/features/filter/git).

### Graph-Based Filtering

Filter configurations based on dependency relationships using graph traversal. Use ellipsis (`...`) to traverse the dependency graph and caret (`^`) to exclude the target from results.

**Syntax variants:**

* `foo...` - Include target and all dependencies (things it depends on)
* `...foo` - Include target and all dependents (things that depend on it)
* `...foo...` - Include target, dependencies, and dependents
* `^foo...` - Include only dependencies (exclude target)
* `...^foo` - Include only dependents (exclude target)
* `...^foo...` - Include dependencies and dependents (exclude target)

```bash
# Find 'service' and everything it depends on
terragrunt find --filter 'service...'


# Find 'vpc' and everything that depends on it
terragrunt find --filter '...vpc'


# Find complete dependency graph for 'db'
terragrunt find --filter '...db...'


# Find dependencies of 'service' but exclude 'service' itself
terragrunt find --filter '^service...'


# Combine graph traversal with path filters (note the use of braces to escape the path)
terragrunt find --filter '{./apps/service}...'


# Combine graph traversal with attribute filters
terragrunt find --filter '...type=unit'


# Refine graph results with intersection
terragrunt find --filter 'service... | external=false'
```

Note

Graph expressions require dependency discovery to work correctly. When using graph expressions, Terragrunt automatically discovers dependency relationships between components. This may add some overhead compared to simple name or path filters.

For more detailed examples and explanations, see the [Filters feature documentation](/features/filter/graph).

### Union (Multiple Filters)

Specify multiple `--filter` flags to combine results using OR logic:

```bash
# Find components named 'unit1' OR 'stack1'
terragrunt find --filter unit1 --filter stack1
```

### The filters file

Instead of specifying filters on the command line, you can store filter queries in a file. By default, Terragrunt automatically reads filter queries from the `.terragrunt-filters` file in your current working directory if it exists.

```bash
# Automatically reads .terragrunt-filters (no flag needed)
terragrunt find


# Use a custom filters file
terragrunt find --filters-file custom-filters.txt


# Disable automatic file reading
terragrunt find --no-filters-file
```

The filters file should contain one filter query per line. Empty lines and lines starting with `#` are ignored:

```text
# Production environment filters
type=unit
./prod/**


# Exclude test units
!name=test-*
```

## Supported Commands

Currently supported in:

* [find](/reference/cli/commands/find)
* [list](/reference/cli/commands/list)
* [run](/reference/cli/commands/run)
* [hcl fmt](/reference/cli/commands/hcl/fmt)
* [hcl validate](/reference/cli/commands/hcl/validate)

Planned for future releases:

* [dag graph](/reference/cli/commands/dag/graph)

## Learn More

For comprehensive examples and advanced usage patterns, see the [Filters feature documentation](/features/filter).

- **Type:** `list(string)`

### `--filter-affected`

Filter components affected by changes between the default branch and HEAD

The `--filter-affected` flag is a convenient shorthand for filtering components that have been modified, added, or removed between the default branch (typically `main`) and `HEAD`. It is equivalent to using `--filter '[main...HEAD]'` (or `--filter '[<defaultBranch>...HEAD]'` if your repository uses a different default branch).

## Usage

```bash
# Find all components affected by changes between main and HEAD
terragrunt find --filter-affected


# List affected components
terragrunt list --filter-affected


# Run plan on affected components
terragrunt run --all --filter-affected -- plan


# Run apply on affected components
terragrunt run --all --filter-affected -- apply
```

## Default Branch Detection

The flag automatically detects your repository’s default branch. It checks:

1. Your Git configuration for `init.defaultBranch`
2. Falls back to `main` if not configured

To use a different branch for comparison, use the `--filter` flag directly with a Git-based filter expression:

```bash
# Compare against a specific branch
terragrunt find --filter '[develop...HEAD]'


# Compare between two specific references
terragrunt find --filter '[v1.0.0...v2.0.0]'
```

## Uncommitted Changes Warning

If you have uncommitted changes in your working directory, Terragrunt will display a warning:

```plaintext
Warning: You have uncommitted changes. The --filter-affected flag may not include all your local modifications.
```

This is because `--filter-affected` compares Git references, not your working directory. To include uncommitted changes, you would need to commit them first or use a different filtering approach.

## Equivalent Filter Expression

The `--filter-affected` flag is equivalent to:

```bash
terragrunt find --filter '[main...HEAD]'
```

Or, if your default branch is different:

```bash
terragrunt find --filter '[<defaultBranch>...HEAD]'
```

## Learn More

For more information about Git-based filtering and advanced usage patterns, see the [Filters feature documentation](/features/filter/git).

- **Type:** `bool`

### `--graph`

Run the provided OpenTofu/Terraform command against the graph of dependencies for the unit in the current working directory.

When this flag is set, Terragrunt will run the specified OpenTofu/Terraform command against the graph of dependencies for the unit in the current working directory. The graph consists of all units that depend on the unit in the current working directory via a `dependency` or `dependencies` blocks, plus all the units that depend on those units, and all the units that depend on those units, and so on, recursively up the tree, up to the Git repository root.

The command will be executed following the order of dependencies: it’ll run on the unit in the current working directory first, then on units that depend on it directly, then on the units that depend on those units, and so on. Note that if the command is `destroy`, it will run in the opposite order (the final dependents, then their dependencies, etc. up to the unit you ran the command in).

## Example Usage

Given the following dependency graph:

![dependency-graph](/_vercel/image?url=_astro%2Fdependency-graph.jq_o4VUG.png\&w=1200\&q=100)

Running `terragrunt run --graph plan` in the `eks` module will lead to the following execution order:

```text
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` units aren’t included in the graph because they are not dependent on the `eks` unit
* Execution is from bottom up based on dependencies

Running `terragrunt run --graph destroy` in the `eks` unit will lead to the following execution order:

```text
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:

* Execution is in reverse order; first are destroyed “top” units and in the end `eks`
* `lambda` units aren’t affected at all

To learn more about how to use this flag, see the [Stacks](/features/stacks) feature documentation.

Caution

When running `graph destroy`, the execution order is reversed compared to other commands. Dependencies will be destroyed in reverse order to ensure resources are safely removed (dependents are destroyed before their dependencies).

Always verify the execution plan before running destructive commands.

Danger

External dependencies (units outside your current working directory) are not automatically included in graph runs.

You must explicitly include them using [`--queue-include-external`](/reference/cli/commands/run#queue-include-external) if they need to be part of the execution.

- **Type:** `bool`
- **Environment variables:** `TG_GRAPH`

### `--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](/features/units/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`](/reference/cli/commands/run#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](/features/units/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`](/reference/cli/commands/run#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](/features/units/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`](/reference/cli/commands/run#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](/features/units/authentication) feature documentation.

- **Type:** `string`
- **Environment variables:** `TG_IAM_ASSUME_ROLE_WEB_IDENTITY_TOKEN`

### `--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](/troubleshooting/debugging) guide.

- **Type:** `bool`
- **Environment variables:** `TG_INPUTS_DEBUG`

### `--no-auto-approve`

Don't automatically append '-auto-approve' to the underlying OpenTofu/Terraform commands run with 'run --all'.

When enabled, Terragrunt will not automatically append the `-auto-approve` flag to destructive commands like `apply` or `destroy` when running with `--all`. This means you’ll be prompted for confirmation before making changes.

- **Type:** `bool`
- **Environment variables:** `TG_NO_AUTO_APPROVE`

### `--no-auto-init`

Don't automatically run init on tofu/terraform commands.

When enabled, Terragrunt will not automatically run `init` before other OpenTofu/Terraform commands.

To learn more about how to use this flag, see the [Auto-init](/features/units/auto-init) feature documentation.

Caution

When `--no-auto-init` is enabled, you must manually run `terragrunt init` if needed. Terragrunt will fail if it detects that initialization is required but auto-init is disabled.

This is particularly important when using custom plugin directories or when working in CI/CD environments.

- **Type:** `bool`
- **Environment variables:** `TG_NO_AUTO_INIT`

### `--no-auto-provider-cache-dir`

Disable the auto-provider-cache-dir feature even when the experiment is enabled.

When enabled, Terragrunt will disable the `auto-provider-cache-dir` feature. This flag allows you to selectively opt-out of the automatic provider caching behavior.

This is useful when you want to maintain control over provider caching in specific environments or scenarios.

- **Type:** `bool`
- **Environment variables:** `TG_NO_AUTO_PROVIDER_CACHE_DIR`

### `--no-auto-retry`

Don't automatically retry commands which fail with transient errors.

When enabled, Terragrunt will not automatically retry commands that fail with transient errors (like network timeouts). By default, Terragrunt will retry such commands a limited number of times.

To learn more about how Terragrunt handles retries, see the [Errors](/features/units/runtime-control#errors) section of the [Runtime Control](/features/units/runtime-control#errors) feature documentation.

- **Type:** `bool`
- **Environment variables:** `TG_NO_AUTO_RETRY`

### `--no-hooks`

Disable Terragrunt hooks during run. Requires the optional-hooks experiment.

Experimental

This flag is gated behind the [`optional-hooks`](/reference/experiments/active#optional-hooks) experiment. Enable it with `--experiment=optional-hooks` or `TG_EXPERIMENT=optional-hooks`; otherwise setting `--no-hooks` returns an error.

Skip Terragrunt hooks during a run.

When enabled, Terragrunt does not execute configured `before_hook`, `after_hook`, or `error_hook` blocks for the run.

- **Type:** `boolean`
- **Environment variables:** `TG_NO_HOOKS`

### `--destroy-dependencies-check`

Enables Terragrunt's dependency validation during destroy operations.


When enabled, Terragrunt will verify if there are dependent units that would be affected by destroying the current unit and show a warning with the list of dependent modules.

Tip

Enabling dependency checks during destroy operations helps prevent accidental destruction of infrastructure that other units depend on.

- **Type:** `bool`
- **Environment variables:** `TG_DESTROY_DEPENDENCIES_CHECK`

### `--parallelism`

Parallelism for --all commands.

Sets the maximum number of concurrent operations when running commands with `--all`. This helps control resource usage and API rate limits when working with multiple units.

Caution

When using `--parallelism` with provider caching, `terraform init` is always executed sequentially if OpenTofu/Terraform provider plugin cache is configured.

To safely run concurrent operations with provider caching, enable the [Provider Cache Server](/features/caching/provider-cache-server/) instead.

- **Type:** `integer`
- **Environment variables:** `TG_PARALLELISM`

### `--provider-cache`

Enables Terragrunt's provider caching.

When enabled, Terragrunt will use its provider caching system to speed up provider downloads.

For more information, see the [Provider Cache Server](/features/caching/provider-cache-server) feature documentation.

Note

The `tofu init` command is always executed sequentially if the provider plugin cache is used without the Provider Cache Server.

- **Type:** `bool`
- **Environment variables:** `TG_PROVIDER_CACHE`

### `--provider-cache-dir`

The path to the Terragrunt provider cache directory. By default, 'terragrunt/providers' folder in the user cache directory.

Specifies the directory where Terragrunt will store cached provider files. This flag is only used when the [Provider Cache Server](/features/caching/provider-cache-server) is enabled.

- **Type:** `string`
- **Environment variables:** `TG_PROVIDER_CACHE_DIR`

### `--provider-cache-hostname`

The hostname of the Terragrunt Provider Cache server. By default, 'localhost'.

Sets the hostname for connecting to the Provider Cache server. This flag is only used when the [Provider Cache Server](/features/caching/provider-cache-server) is enabled.

- **Type:** `string`
- **Environment variables:** `TG_PROVIDER_CACHE_HOSTNAME`

### `--provider-cache-port`

The port of the Terragrunt Provider Cache server. By default, assigned automatically.

Specifies the port number for connecting to the Provider Cache server. This flag is only used when the [Provider Cache Server](/features/caching/provider-cache-server) is enabled.

- **Type:** `string`
- **Environment variables:** `TG_PROVIDER_CACHE_PORT`

### `--provider-cache-registry-names`

The list of remote registries to cached by Terragrunt Provider Cache server. By default, 'registry.terraform.io', 'registry.opentofu.org'.

Specifies which provider registries should be cached by the Provider Cache server. This flag is only used when the [Provider Cache Server](/features/caching/provider-cache-server) is enabled.

- **Type:** `string`
- **Environment variables:** `TG_PROVIDER_CACHE_REGISTRY_NAMES`

### `--provider-cache-token`

The token for authentication to the Terragrunt Provider Cache server. By default, assigned automatically.

Sets the authentication token for connecting to the Provider Cache server. This flag is only used when the [Provider Cache Server](/features/caching/provider-cache-server) is enabled.

- **Type:** `string`
- **Environment variables:** `TG_PROVIDER_CACHE_TOKEN`

### `--queue-exclude-dir`

Unix-style glob of directories to exclude from the queue of Units to run.

Alias for --filter

This flag is an alias for the [`--filter` flag](/reference/cli/commands/run#filter).

When using this flag, the equivalent filter expression is used instead.

e.g.

```bash
terragrunt run --all --queue-exclude-dir "prod/**" -- plan
```

is equivalent to:

```bash
terragrunt run --all --filter "!{./prod/**}" -- plan
```

- **Type:** `list(string)`
- **Environment variables:** `TG_QUEUE_EXCLUDE_DIR`

### `--queue-exclude-external`

Exclude external dependencies from the queue of Units to run.

Deprecated

This flag is deprecated and will be removed in a future version of Terragrunt. External dependencies are now excluded by default, making this flag unnecessary.

Use [`--filter` flag](/reference/cli/commands/run#filter) with the expression `{./**}...` if you need to include external dependencies.

- **Type:** `bool`
- **Environment variables:** `TG_QUEUE_EXCLUDE_EXTERNAL`

### `--queue-excludes-file`

Path to a file with a list of directories that need to be excluded when running `run --all` commands.

Alias for --filters-file

This flag leverages the same underlying functionality as the [`--filters-file` flag](/reference/cli/commands/run#filters-file).

When using this flag, the `.terragrunt-excludes` file will be parsed, and converted to the equivalent filter expressions.

e.g.

excludes-file.txt

```text
prod
```

```bash
terragrunt run --all --queue-excludes-file ./excludes-file.txt -- plan
```

is equivalent to:

filters-file.txt

```text
!{./prod}
```

```bash
terragrunt run --all --filters-file ./filters-file.txt -- plan
```

- **Type:** `string`
- **Default:** `.terragrunt-excludes`
- **Environment variables:** `TG_QUEUE_EXCLUDES_FILE`

### `--queue-ignore-dag-order`

Ignore DAG order for --all commands.

When enabled, Terragrunt will ignore the dependency order when running commands with [`--all`](/reference/cli/commands/run#all). This means units will be executed in arbitrary order, which can be useful for read-only operations like `plan`.

Note that this can lead to errors if used with commands that modify state, as dependencies might be processed in the wrong order.

To learn more about how to use this flag, see the [Stacks](/features/stacks) feature documentation.

- **Type:** `bool`
- **Environment variables:** `TG_QUEUE_IGNORE_DAG_ORDER`

### `--queue-ignore-errors`

Continue processing Units even if a dependency fails.

When enabled, Terragrunt will continue processing remaining units even if one fails. This can be useful when you want to see all potential errors in your configuration, rather than stopping at the first failure.

Note that this may lead to incomplete or inconsistent states if used with commands that modify infrastructure.

To learn more about how to use this flag, see the [Stacks](/features/stacks) feature documentation.

Danger

Using `--queue-ignore-errors` can lead to inconsistent state if dependencies fail but dependent modules continue running.

Use this flag with caution, especially with `apply` or `destroy` commands.

For more fine-grained error handling, see the [errors block](/reference/hcl/blocks#errors) in the HCL reference.

- **Type:** `bool`
- **Environment variables:** `TG_QUEUE_IGNORE_ERRORS`

### `--queue-include-dir`

Unix-style glob of directories to include in the queue of Units to run.

Alias for --filter

This flag is an alias for the [`--filter` flag](/reference/cli/commands/run#filter).

When using this flag, the equivalent filter expression is used instead.

e.g.

```bash
terragrunt run --all --queue-include-dir "prod/**" -- plan
```

is equivalent to:

```bash
terragrunt run --all --filter "{./prod/**}" -- plan
```

- **Type:** `list(string)`
- **Environment variables:** `TG_QUEUE_INCLUDE_DIR`

### `--queue-include-external`

Include external dependencies in the queue of Units to run.

Alias for --filter

This flag is an alias for the [`--filter` flag](/reference/cli/commands/run#filter).

When using this flag, the equivalent filter expression is used instead.

e.g.

```bash
terragrunt run --all --queue-include-external -- plan
```

is equivalent to:

```bash
terragrunt run --all --filter "{./**}..." -- plan
```

- **Type:** `bool`
- **Environment variables:** `TG_QUEUE_INCLUDE_EXTERNAL`

### `--queue-include-units-reading`

If flag is set, 'run --all' will only run the command against Terragrunt units that read the specified file via an HCL function or include.

Alias for --filter

This flag is an alias for the [`--filter` flag](/reference/cli/commands/run#filter).

When using this flag, the equivalent filter expression is used instead.

e.g.

```bash
terragrunt run --all --queue-include-units-reading shared.hcl -- plan
```

is equivalent to:

```bash
terragrunt run --all --filter 'reading=shared.hcl' -- plan
```

- **Type:** `string`
- **Environment variables:** `TG_QUEUE_INCLUDE_UNITS_READING`

### `--queue-strict-include`

Only process the directories matched by --queue-include-dir.

Deprecated

This flag is deprecated and will be removed in a future version of Terragrunt. Terragrunt performs strict inclusion by default, so this flag is no longer needed.

- **Type:** `bool`
- **Environment variables:** `TG_QUEUE_STRICT_INCLUDE`

### `--report-file`

The path where a run report should be generated.

By default, the format of the report will be automatically detected based on the file extension. A `.csv` extension will generate a CSV report, and a `.json` extension will generate a JSON report. Anything else will default to generating a CSV report.

To explicitly specify the format of the report, use the [report-format](/reference/cli/commands/run/#report-format) flag.

For more information, see the [Run Report](/features/stacks/run-report) feature.

- **Type:** `string`
- **Environment variables:** `TG_REPORT_FILE`

### `--report-format`

The format of the run report.

The supported formats are:

* `csv`
* `json`

The default is `csv`.

For more information, see the [Run Report](/features/stacks/run-report) feature.

- **Type:** `string`
- **Environment variables:** `TG_REPORT_FORMAT`

### `--report-schema-file`

When passed in, a JSON schema for the report will be generated at the specified path.


This is useful when you need a programmatic way to validate that the report conforms to an expected schema.

### Example

```bash
terragrunt run --all plan --report-schema-file report.schema.json
```

The schema will be generated at the given path in the current working directory.

For more information, see the [Run Report](/features/stacks/run-report) feature.

- **Type:** `string`
- **Environment variables:** `TG_REPORT_SCHEMA_FILE`

### `--source`

Download OpenTofu/Terraform configurations from the specified source into a temporary folder, and run Terraform in that temporary folder.

Specifies a source URL where Terragrunt should download the OpenTofu/Terraform configuration. This overrides any `source` parameters specified in the Terragrunt configuration files.

The configuration will be downloaded into a temporary folder, and Terragrunt will execute OpenTofu/Terraform commands in that folder.

Example:

```bash
terragrunt run plan --source github.com/example/infrastructure//modules/vpc
```

This is particularly useful when:

* Testing changes to modules without modifying the source in your configuration.
* Using a specific version or branch of your infrastructure modules.
* Running configurations from a different source than what’s specified in your Terragrunt files.

- **Type:** `string`
- **Environment variables:** `TG_SOURCE`

### `--source-map`

Replace any source URL (including the source URL of a config pulled in with dependency blocks) that has root source with dest.

Allows you to replace source URLs that match a specified pattern with a different URL. This affects both direct source references and sources specified in dependency blocks.

The format is `source-regex=replacement-source`.

For example:

```bash
terragrunt run plan --source-map "git::ssh://git@github.com/org/repo.git=../local/repo"
```

This will replace any source URL that matches `git::ssh://git@github.com/org/repo.git` with `../local/repo`.

Caution

Source mapping only performs literal matches on the URL portion. For example, a map key of `ssh://git@github.com/org/repo.git` will not match sources of the form `git::ssh://git@github.com/org/repo.git`. The latter requires a map key of `git::ssh://git@github.com/org/repo.git`.

- **Type:** `string`
- **Environment variables:** `TG_SOURCE_MAP`

### `--source-update`

Delete the contents of the temporary folder to clear out any old, cached source code before downloading new source code into it.

When enabled, Terragrunt will delete any existing content in the temporary download directory before fetching new source code into it. This ensures you’re working with a fresh copy of the source code.

Example:

```bash
terragrunt run plan --source-update
```

- **Type:** `bool`
- **Environment variables:** `TG_SOURCE_UPDATE`

### `--summary-disable`

Disables the summary output at the end of a run.

When enabled, Terragrunt will disable the summary output at the end of a run.

For more information, see the [Run Report](/features/stacks/run-report#disabling-the-summary) feature.

- **Type:** `bool`
- **Environment variables:** `TG_SUMMARY_DISABLE`

### `--summary-per-unit`

Summarize each unit in the run summary.

When enabled, Terragrunt will break down the run summary by unit. The units are sorted by result, then duration, with the longest-running units shown first.

For more information, see the [Run Report](/features/stacks/run-report) feature.

- **Type:** `bool`
- **Environment variables:** `TG_SUMMARY_PER_UNIT`

### `--tf-forward-stdout`

If specified, the output of OpenTofu/Terraform commands will be printed as is, without being integrated into the Terragrunt log.

By default, Terragrunt integrates OpenTofu/Terraform output into its own logging system. When this flag is enabled, OpenTofu/Terraform output will be printed directly to stdout without Terragrunt’s logging wrapper.

For example, without `--tf-forward-stdout`:

```bash
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:
```

With `--tf-forward-stdout`:

```bash
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:
```

- **Type:** `bool`
- **Environment variables:** `TG_TF_FORWARD_STDOUT`

### `--tf-path`

Path to the OpenTofu/Terraform binary. Default is tofu (on PATH).

Specifies the path to the OpenTofu/Terraform binary that Terragrunt should use. By default, Terragrunt will look for a binary named `tofu` in your system’s PATH.

This is useful when:

* You have multiple versions of OpenTofu/Terraform installed.
* The binary is not in your PATH.
* You want to use a specific version for certain operations.
* You want to switch between OpenTofu and Terraform binaries.

Example:

```bash
terragrunt run plan --tf-path=/usr/local/bin/tofu
```

Note that if you only have `terraform` installed, and it is available in your `PATH`, Terragrunt will automatically use that binary.

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.

- **Type:** `string`
- **Environment variables:** `TG_TF_PATH`

### `--units-that-include`

If flag is set, 'run --all' will only run the command against Terragrunt units that include the specified file.

Alias for --filter

This flag is an alias for the [`--filter` flag](/reference/cli/commands/run#filter).

When using this flag, the equivalent filter expression is used instead.

e.g.

```bash
terragrunt run --all --units-that-include shared.hcl -- plan
```

is equivalent to:

```bash
terragrunt run --all --filter 'reading=shared.hcl' -- plan
```

- **Type:** `string`
- **Environment variables:** `TG_UNITS_THAT_INCLUDE`

### `--use-partial-parse-config-cache`

Enables caching of includes during partial parsing operations. Will also be used for the --iam-assume-role option if provided.

This flag can be used to drastically decrease time required for parsing Terragrunt configuration files. The effect will only show if a lot of similar includes are expected such as the root terragrunt configuration (e.g. `root.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:

* Building the Directed Acyclic Graph (DAG) during a `run --all` command where only the `dependency` blocks need to be evaluated to determine run order.
* Parsing the `terraform` block to determine state configurations for fetching `dependency` outputs.
* Determining whether Terragrunt execution behavior has to change like for `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.

Caution

This is an experimental feature. While it can significantly improve performance with frequently included configurations, the caching behavior may lead to unexpected results in some edge cases due to HCL’s dynamic nature.

Test thoroughly in your environment before using in production environments.

- **Type:** `bool`
- **Environment variables:** `TG_USE_PARTIAL_PARSE_CONFIG_CACHE`

### `--version-manager-file-name`

File names used during the computation of the cache key for the version manager files.

By default, terragrunt is specifying:

```shell
.terraform-version
.tool-versions
.mise.toml
mise.toml
```

- **Type:** `string`
- **Environment variables:** `TG_VERSION_MANAGER_FILE_NAME`

### `--no-cas`

Disable the CAS (Content Addressable Storage) feature even when the experiment is enabled.

When enabled, Terragrunt skips all CAS operations even if the `cas` experiment is active. Use this to temporarily bypass CAS without removing the experiment flag.

Generation or runs error when `update_source_with_cas = true` is set on any `unit`, `stack`, or `terraform` block reachable from the current invocation, since relative sources rewritten by CAS cannot be resolved without it.

- **Type:** `bool`
- **Environment variables:** `TG_NO_CAS`

### `--cas-clone-depth`

When using CAS, pass this value to git clone --depth (default 1; -1 clones full history).

Experimental

This flag only has an effect when the [`cas`](/reference/experiments/active#cas) experiment is enabled. Enable it with `--experiment=cas` or `TG_EXPERIMENT=cas`.

Controls the `--depth` value the CAS (Content Addressable Storage) uses when cloning a Git source. The default of `1` performs a shallow clone of the latest commit. Negative values clone the full history by omitting `--depth` entirely; zero is rejected because Git requires a positive depth.

When passing a negative value, use the `--cas-clone-depth=-1` form so the leading dash isn’t parsed as a flag.

- **Type:** `integer`
- **Default:** `1`
- **Environment variables:** `TG_CAS_CLONE_DEPTH`