find

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

Find all configurations (units and stacks) in the current directory.

terragrunt find

Find all configurations in a different directory.

terragrunt find --working-dir /path/to/working/dir

Disable color output.

terragrunt find --no-color

Find all configurations in the current directory and emit them as a JSON string.

terragrunt find --format 'json'

Find all configurations and output them in JSON format (alias for --format=json).

terragrunt find --json

Sort configurations based on their dependencies using DAG mode.

terragrunt find --dag

Sort configurations based on dependency graph as if running plan command.

$ 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

Sort configurations based on dependency graph as if running destroy command.

$ 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

Include dependency information in the output.

terragrunt find --dependencies --format 'json'

Include exclude configuration in the output.

terragrunt find --exclude --format 'json'

Include external dependencies in the output.

terragrunt find --dependencies --external --format 'json'

Color Output

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

Color Coding

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

• Units are displayed in blue
• Stacks are displayed in green

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:

terragrunt find --format=json

or the shorter alias:

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:

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:

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:

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:

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:

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:

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:

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:

terragrunt find --hidden

Disabling Color Output

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

terragrunt find --no-color

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

Working Directory

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

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

Flags

--format

Format the results as specified. Supported values (text, json). Default: text.

This is particularly useful when you need to process the results programmatically or integrate with other tools.

Example:

$ terragrunt find --format=json | jq '.[:3]'
[
  {
    "type": "stack",
    "path": "basic"
  },
  {
    "type": "unit",
    "path": "basic/units/chick"
  },
  {
    "type": "unit",
    "path": "basic/units/chicken"
  }
]

Type: string

Environment Variables:

• TG_FORMAT

--json

Output results in JSON format. This is equivalent to using `--format=json`.

This flag is a convenient shorthand for --format=json. It’s particularly useful when you need to process the results programmatically or integrate with other tools.

Example:

$ terragrunt find --json | jq '.[:3]'
[
  {
    "type": "stack",
    "path": "basic"
  },
  {
    "type": "unit",
    "path": "basic/units/chick"
  },
  {
    "type": "unit",
    "path": "basic/units/chicken"
  }
]

Equivalent Flags

The --json flag is equivalent to --format=json. You can use either one to get the same JSON output.

Type: bool

Environment Variables:

• TG_JSON

--dag

Output in DAG mode.

Outputs configurations in DAG mode, which sorts configurations by dependency order by relationship in the dependency graph.

By default, configurations are sorted alphabetically:

$ terragrunt find
live/dev/db
live/dev/ec2
live/dev/vpc
live/prod/db
live/prod/ec2
live/prod/vpc

When the --dag flag is used, configurations are sorted by dependency order (dependencies before their dependents):

$ terragrunt find --dag
live/dev/vpc
live/prod/vpc
live/dev/db
live/prod/db
live/dev/ec2
live/prod/ec2

When not used in the JSON format:

$ terragrunt find --json --dependencies
[
  {
    "type": "unit",
    "path": "live/dev/db",
    "dependencies": [
      "live/dev/vpc"
    ]
  },
  {
    "type": "unit",
    "path": "live/dev/ec2",
    "dependencies": [
      "live/dev/vpc",
      "live/dev/db"
    ]
  },
  {
    "type": "unit",
    "path": "live/dev/vpc"
  },
  {
    "type": "unit",
    "path": "live/prod/db",
    "dependencies": [
      "live/prod/vpc"
    ]
  },
  {
    "type": "unit",
    "path": "live/prod/ec2",
    "dependencies": [
      "live/prod/vpc",
      "live/prod/db"
    ]
  },
  {
    "type": "unit",
    "path": "live/prod/vpc"
  }
]

Results are sorted by path.

When combined with the JSON format:

$ terragrunt find --json --dependencies --dag
[
  {
    "type": "unit",
    "path": "live/dev/vpc"
  },
  {
    "type": "unit",
    "path": "live/prod/vpc"
  },
  {
    "type": "unit",
    "path": "live/dev/db",
    "dependencies": [
      "live/dev/vpc"
    ]
  },
  {
    "type": "unit",
    "path": "live/prod/db",
    "dependencies": [
      "live/prod/vpc"
    ]
  },
  {
    "type": "unit",
    "path": "live/dev/ec2",
    "dependencies": [
      "live/dev/vpc",
      "live/dev/db"
    ]
  },
  {
    "type": "unit",
    "path": "live/prod/ec2",
    "dependencies": [
      "live/prod/vpc",
      "live/prod/db"
    ]
  }
]

Type: boolean

Environment Variables:

• TG_DAG

--hidden

Find configurations in hidden directories.

Example:

terragrunt find --hidden

Type: bool

Environment Variables:

• TG_HIDDEN

--dependencies

Include dependency information in the output.

When enabled, the output will include information about dependencies between configurations. This is particularly useful when combined with JSON output format to understand the dependency relationships in your codebase.

Example:

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

Type: bool

Environment Variables:

• TG_DEPENDENCIES

--find-exclude

Include exclude configuration in the output

Include exclude configuration in the output. When enabled, the JSON output will include the configurations of the exclude block in the discovered units.

Usage

--exclude

Examples

Show exclude configurations in JSON format:

terragrunt find --exclude --format=json

Show exclude configurations with queue construct simulation:

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

Behavior

When enabled, the JSON output will include any exclude block configurations found in the units:

$ terragrunt find --exclude --format=json | jq
[
  {
    "type": "unit",
    "path": "action/exclude-apply",
    "exclude": {
      "exclude_dependencies": true,
      "actions": [
        "apply"
      ],
      "if": true
    }
  },
  {
    "type": "unit",
    "path": "action/exclude-plan",
    "exclude": {
      "exclude_dependencies": true,
      "actions": [
        "plan"
      ],
      "if": true
    }
  },
  {
    "type": "unit",
    "path": "all-except-output/app1",
    "exclude": {
      "exclude_dependencies": true,
      "actions": [
        "all_except_output"
      ],
      "if": true
    }
  }
]

Note that you can combine this with the --queue-construct-as flag to dry-run behavior relevant to excludes.

$ terragrunt find --exclude --queue-construct-as=plan --format=json | jq
[
  {
    "type": "unit",
    "path": "action/exclude-apply",
    "exclude": {
      "exclude_dependencies": true,
      "actions": [
        "apply"
      ],
      "if": true
    }
  }
]

Type: boolean

Environment Variables:

• TG_FIND_EXCLUDE

--external

Include external dependencies in the output.

When enabled, units outside the working directory can be included as part of the output, if any unit depends on them. This is useful when you need to understand all dependency relationships, including those that don’t exist in the current directory.

Example:

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": []
  }
]

Type: bool

Environment Variables:

• TG_EXTERNAL

--queue-construct-as

Sort output based on the dependency graph, as if a particular command was run. This flag implies the `--dag` flag. The flag has a shorter alias `--as`.

Sort output based on the dependency graph, as if a particular command was run. This flag implies the --dag flag.

The flag has a shorter alias --as.

Usage

--queue-construct-as=COMMAND
--as=COMMAND

Where COMMAND is the command to simulate (e.g., plan, destroy).

Examples

Sort output as if running plan command (dependencies after dependents):

terragrunt find --queue-construct-as=plan

Sort output as if running destroy command (dependencies before dependents):

terragrunt find --queue-construct-as=destroy

Behavior

When using plan command, all dependent units will appear after the units they depend on.

When using destroy command, all dependent units will appear before the units they depend on.

Note: This flag implies the --dag flag.

Type: string

Aliases:

• --as

Environment Variables:

• TG_QUEUE_CONSTRUCT_AS