---
name: find
path: find
category: discovery
sidebar:
  order: 700
description: Find relevant Terragrunt configurations.
usage: |
  The `find` command helps you discover Terragrunt configurations in your codebase.

  It recursively searches for `terragrunt.hcl` and `terragrunt.stack.hcl` files and displays them in formatted output.
examples:
  - description: |
      Find all configurations (units and stacks) in the current directory.
    code: |
      terragrunt find
  - description: |
      Find all configurations in a different directory.
    code: |
      terragrunt find --working-dir /path/to/working/dir
  - description: |
      Disable color output.
    code: |
      terragrunt find --no-color
  - description: |
      Find all configurations in the current directory and emit them as a JSON string.
    code: |
      terragrunt find --format 'json'
  - description: |
      Find all configurations and output them in JSON format (alias for --format=json).
    code: |
      terragrunt find --json
  - description: |
      Sort configurations based on their dependencies using DAG mode.
    code: |
      terragrunt find --dag
  - description: |
      Sort configurations based on dependency graph as if running plan command.
    code: |
      $ terragrunt find --queue-construct-as=plan
      stacks/live/dev
      stacks/live/prod
      units/live/dev/vpc
      units/live/prod/vpc
      units/live/dev/db
      units/live/prod/db
      units/live/dev/ec2
      units/live/prod/ec2

  - description: |
      Sort configurations based on dependency graph as if running destroy command.
    code: |
      $ terragrunt find --queue-construct-as=destroy
      stacks/live/dev
      stacks/live/prod
      units/live/dev/ec2
      units/live/prod/ec2
      units/live/dev/db
      units/live/prod/db
      units/live/dev/vpc
      units/live/prod/vpc

  - description: |
      Include dependency information in the output.
    code: |
      terragrunt find --dependencies --format 'json'
  - description: |
      Include exclude configuration in the output.
    code: |
      terragrunt find --exclude --format 'json'
  - description: |
      Include external dependencies in the output.
    code: |
      terragrunt find --dependencies --external --format 'json'
flags:
  - find-format
  - find-json
  - find-dag
  - find-hidden
  - find-dependencies
  - find-exclude
  - find-include
  - find-external
  - queue-construct-as
---

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

## Color Output

When used without any flags, all units and stacks discovered in the current working directory are displayed in colorful text format.

![find](../../assets/img/screenshots/find.png)

<Aside type="note" title="Color Coding">

Discovered configurations are color coded to help you identify them at a glance:

- <Badge text="Units" style={{ backgroundColor: '#1B46DD', color: '#FFFFFF' }} /> are displayed in blue
- <Badge text="Stacks" style={{ backgroundColor: '#2E8B57', color: '#FFFFFF' }} /> are displayed in green

</Aside>

## Output Formats

The `find` command supports two output formats:

### Text Format (Default)

The default text format displays each configuration on a new line, with color coding for different types.

### JSON Format

You can output the results in JSON format using either:

```bash
terragrunt find --format=json
```

or the shorter alias:

```bash
terragrunt find --json
```

The JSON output includes additional metadata about each configuration, such as its type (unit or stack) and path.

## DAG Mode

The `find` command supports DAG mode to sort output based on dependencies using the `--dag` flag.

When using DAG mode, configurations with no dependencies appear first, followed by configurations that depend on them, maintaining the correct dependency order:

```bash
terragrunt find --dag
unitA           # no dependencies
unitB           # no dependencies
unitC           # depends on unitA
unitD           # depends on unitC
```

If multiple configurations share common dependencies, they will be sorted in lexical order.

## Queue Construct As

The `find` command supports the `--queue-construct-as` flag (or its shorter alias `--as`) to sort output based on the dependency graph, as if a particular command was run.

For example, when using the `plan` command:

```bash
terragrunt find --queue-construct-as=plan
stacks/live/dev
stacks/live/prod
units/live/dev/vpc
units/live/prod/vpc
units/live/dev/db
units/live/prod/db
units/live/dev/ec2
units/live/prod/ec2
```

This will sort the output based on the dependency graph, as if the `plan` command was run. All dependent units will appear *after* the units they depend on.

When using the `destroy` command:

```bash
terragrunt find --as=destroy
stacks/live/dev
stacks/live/prod
units/live/dev/ec2
units/live/prod/ec2
units/live/dev/db
units/live/prod/db
units/live/dev/vpc
units/live/prod/vpc
```

This will sort the output based on the dependency graph, as if the `destroy` command was run. All dependent units will appear *before* the units they depend on.

**Note:** The `--queue-construct-as` flag implies the `--dag` flag.

## Dependencies

You can include dependency information in the output using the `--dependencies` flag. When enabled, the JSON output will include the dependency relationships between configurations:

```bash
terragrunt find --dependencies --format=json
[
  {
    "type": "unit",
    "path": "unitA",
    "dependencies": []
  },
  {
    "type": "unit",
    "path": "unitB",
    "dependencies": ["../unitA", "../../external/unitC"]
  }
]
```

## Exclude Configuration

You can include exclude configuration in the output using the `--exclude` flag. When enabled, the JSON output will include the configurations of the `exclude` block in the discovered units:

```bash
terragrunt find --exclude --format=json
[
  {
    "type": "unit",
    "path": "action/exclude-apply",
    "exclude": {
      "exclude_dependencies": true,
      "actions": [
        "apply"
      ],
      "if": true
    }
  }
]
```

You can combine this with the `--queue-construct-as` flag to dry-run behavior relevant to excludes:

```bash
terragrunt find --exclude --queue-construct-as=plan --format=json
```

`find` will remove any units that would match the exclude configuration.

## External Dependencies

By default, external dependencies (those outside the working directory) are not part of the overall results (although, they will be mentioned in the dependency section of the JSON output). Use the `--external` flag to include them as top-level results:

```bash
terragrunt find --dependencies --external --format=json
[
  {
    "type": "unit",
    "path": "internal/unitA",
    "dependencies": []
  },
  {
    "type": "unit",
    "path": "internal/unitB",
    "dependencies": ["../unitA", "../../external/unitC"]
  },
  {
    "type": "unit",
    "path": "external/unitC",
    "dependencies": []
  }
]
```

## Hidden Configurations

By default, hidden directories (those starting with `.`) are excluded from the search. Use the `--hidden` flag to include them:

```bash
terragrunt find --hidden
```

## Disabling Color Output

You can disable color output by using the global `--no-color` flag:

```bash
terragrunt find --no-color
```

When stdout is redirected, color output is disabled automatically to prevent undesired interference with other tools.

![find-no-color](../../assets/img/screenshots/find-no-color.png)

## Working Directory

You can change the working directory for `find` by using the global `--working-dir` flag:

```bash
terragrunt find --working-dir=/path/to/working/dir
```
