---
name: filter
description: Filter configurations using a flexible query language
type: list(string)
---

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

<Aside type="tip" title="Experimental Feature">
This feature is currently experimental and not yet complete. See the [filter-flag experiment documentation](/docs/reference/experiments#filter-flag) for details on what is and isn't supported.

Usage of the filter flag requires usage of the `filter-flag` experiment, like so:

```bash
terragrunt find --experiment filter-flag --filter 'foo'
```

Examples below will omit the `--experiment filter-flag` flag for brevity.
</Aside>

The `--filter` flag provides a sophisticated querying syntax for targeting specific [units](/docs/features/units) and [stacks](/docs/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'
```

<Aside type="tip" title="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](/docs/reference/hcl/functions/#mark_as_read) for more information on how Terragrunt tracks files that are read during parsing.

</Aside>

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

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

## Supported Commands

Currently supported in:
- [find](/docs/reference/cli/commands/find)
- [list](/docs/reference/cli/commands/list)
- [run](/docs/reference/cli/commands/run)
- [hcl fmt](/docs/reference/cli/commands/hcl/fmt)
- [hcl validate](/docs/reference/cli/commands/hcl/validate)

Planned for future releases:
- [dag graph](/docs/reference/cli/commands/dag/graph)

## Learn More

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