---
name: run
path: run
category: main
sidebar:
  order: 100
description: '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:
  - description: |
      Run the plan command.
    code: |
      terragrunt run plan
      # Shortcut:
      # terragrunt plan
  - description: |
      Run the plan command, and pass additional arguments.
    code: |
      terragrunt run -- output -json
      # Shortcut:
      # terragrunt output -json
flags:
  - all
  - auth-provider-cmd
  - config
  - json-out-dir
  - dependency-fetch-output-from-state
  - disable-bucket-update
  - disable-command-validation
  - download-dir
  - out-dir
  - engine-cache-path
  - engine-log-level
  - engine-skip-check
  - experimental-engine
  - feature
  - filter
  - filter-affected
  - graph
  - iam-assume-role
  - iam-assume-role-duration
  - iam-assume-role-session-name
  - iam-assume-role-web-identity-token
  - inputs-debug
  - no-auto-approve
  - no-auto-init
  - no-auto-provider-cache-dir
  - no-auto-retry
  - destroy-dependencies-check
  - parallelism
  - provider-cache
  - provider-cache-dir
  - provider-cache-hostname
  - provider-cache-port
  - provider-cache-registry-names
  - provider-cache-token
  - queue-exclude-dir
  - queue-exclude-external
  - queue-excludes-file
  - queue-ignore-dag-order
  - queue-ignore-errors
  - queue-include-dir
  - queue-include-external
  - queue-include-units-reading
  - queue-strict-include
  - report-file
  - report-format
  - report-schema-file
  - source
  - source-map
  - source-update
  - summary-disable
  - summary-per-unit
  - tf-forward-stdout
  - tf-path
  - units-that-include
  - use-partial-parse-config-cache
  - version-manager-file-name
---

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](/docs/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
```

<Aside type="tip" title="Learn More About Filtering">

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

</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](/docs/reference/hcl/blocks/#dependency).
</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](/docs/features/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>
