---
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.

Currently, the `--filter` flag is only available in the `find` and `list` commands. Support for the `run` command is planned for a future release.
</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'
```

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

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

Planned for future releases:
- [run](/docs/reference/cli/commands/run)
- [hcl fmt](/docs/reference/cli/commands/hcl/fmt)
- [hcl validate](/docs/reference/cli/commands/hcl/validate)

## Learn More

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