Run - Terragrunt — ContextQMD

import { Aside } from '@astrojs/starlight/components';

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.

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

For comprehensive examples and advanced usage patterns, see the Filters feature documentation.

</Aside>

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

<Aside type="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.

</Aside> <Aside type="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.

</Aside> <Aside type="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. </Aside>