list

Usage

The list command helps you discover and display Terragrunt configurations in your codebase. It provides various output formats and options to help you understand the structure and dependencies of your Terragrunt configurations.

Examples

List all units in a typical multi-environment infrastructure setup.

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

List all units in long format, showing unit types and paths.

$ terragrunt list -l
Type  Path
unit  live/dev/db
unit  live/dev/ec2
unit  live/dev/vpc
unit  live/prod/db
unit  live/prod/ec2
unit  live/prod/vpc

List all units in tree format to visualize the infrastructure hierarchy.

$ terragrunt list -T
.
╰── live
    ├── dev
    │   ├── db
    │   ├── ec2
    │   ╰── vpc
    ╰── prod
        ├── db
        ├── ec2
        ╰── vpc

List all units with their dependencies to understand infrastructure relationships.

$ terragrunt list -l --dependencies
Type  Path           Dependencies
unit  live/dev/db    live/dev/vpc
unit  live/dev/ec2   live/dev/db, live/dev/vpc
unit  live/dev/vpc
unit  live/prod/db   live/prod/vpc
unit  live/prod/ec2  live/prod/db, live/prod/vpc
unit  live/prod/vpc

List all units in dependency order (DAG) to understand deployment sequence.

$ terragrunt list -l --dag --dependencies
Type  Path          Dependencies
unit  b-dependency
unit  a-dependent   b-dependency

List all units in dependency order as if running plan command.

$ terragrunt list --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

List all units in dependency order as if running destroy command.

$ terragrunt list --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

Output Formats

The list command supports multiple output formats to help you visualize your Terragrunt configurations in different ways:

Text Format (Default)

The default text format provides a simple, space-separated list of configurations.

It will display all configurations that fit in the width of your terminal. When configurations exceed the width of your terminal, it will wrap to the next line.

Long Format

The long format provides additional details about each configuration, including its type:

Tree Format

The tree format provides a hierarchical view of your configurations:

By default, configurations in tree format are displayed ordered by name and grouped by directory:

.
╰── live
    ├── dev
    │   ├── db
    │   ├── ec2
    │   ╰── vpc
    ╰── prod
        ├── db
        ├── ec2
        ╰── vpc

DAG Mode

The list command supports DAG mode to sort and group 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.

For example, in default text format:

# Default alphabetical order
$ terragrunt list
a-dependent b-dependency

# DAG mode order
$ terragrunt list --dag
b-dependency a-dependent

When using --dag with the tree format, configurations are sorted by dependency order and grouped by relationship in the dependency graph:

$ terragrunt list --tree --dag
.
├── live/dev/vpc
│   ├── live/dev/db
│   │   ╰── live/dev/ec2
│   ╰── live/dev/ec2
╰── live/prod/vpc
    ├── live/prod/db
    │   ╰── live/prod/ec2
    ╰── live/prod/ec2

Queue Construct As

The list 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 list --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 list --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

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 and Discovery

Dependencies

Include dependency information in the output using the --dependencies flag. When combined with different grouping options, this provides powerful ways to visualize your infrastructure’s dependency structure.

External Dependencies

Use the --external flag to discover and include dependencies that exist outside your current working directory. This is particularly useful when working with shared modules or cross-repository dependencies.

Hidden Configurations

By default, Terragrunt excludes configurations in hidden directories (those starting with a dot). Use the --hidden flag to include these configurations in the output.

Working Directory

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

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

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

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

Flags

--format

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

Controls how the list results are displayed:

• text (default): Simple space-separated list of configurations. Best for quick overview and scripting.
• long: Detailed view showing type (unit/stack), path, and module information. Useful for auditing and documentation.
• tree: Hierarchical view showing directory structure. Perfect for understanding infrastructure organization.

These values all have shortcuts as standalone flags:

• --long / -l for long
• --tree / -T for tree

Examples:

# Default text format - Great for quick overview
$ terragrunt list
live/dev/db    live/dev/ec2   live/dev/vpc
live/prod/db   live/prod/ec2  live/prod/vpc

# Long format - Useful for reading structured information quickly
$ terragrunt list -l
Type  Path           Dependencies
unit  live/dev/db    live/dev/vpc
unit  live/dev/ec2   live/dev/db, live/dev/vpc
unit  live/dev/vpc
unit  live/prod/db   live/prod/vpc
unit  live/prod/ec2  live/prod/db, live/prod/vpc
unit  live/prod/vpc

# Tree format - Optimal for visualizing structure
$ terragrunt list -T
.
╰── live
    ├── dev
    │   ├── db
    │   ├── ec2
    │   ╰── vpc
    ╰── prod
        ├── db
        ├── ec2
        ╰── vpc

The examples above demonstrate a typical multi-environment infrastructure setup with networking, compute, and data layers. Each format provides a different perspective on the same infrastructure, making it easier to understand and manage your Terragrunt configurations.

Type: string

Environment Variables:

• TG_FORMAT

--hidden

Include hidden directories in list results.

Controls whether hidden directories (those starting with a dot) are included in the list results.

By default, Terragrunt excludes hidden directories from the list output to reduce noise and focus on your primary infrastructure components. However, there may be cases where you want to see all configurations, including those in hidden directories.

Example:

$ terragrunt list -l
Type  Path
stack stack
unit  unit

$ terragrunt list -l --hidden
Type  Path
unit  .hide/unit
stack stack
unit  unit

Type: boolean

Environment Variables:

• TG_HIDDEN

--dependencies

Include dependencies in list results.

Controls whether dependency information is included in the list output. When enabled, Terragrunt will analyze and display the dependency relationships between configurations.

This flag is particularly powerful when combined with different output formats and sorting options:

• With --format=long: Shows dependencies in a tabular format
• With --format=json: Includes full dependency ancestry in JSON output

Tip

Combine --dependencies with --sort=dag and --group-by=dag (or just use --dag) to get a complete picture of your infrastructure’s deployment sequence.

Type: boolean

Environment Variables:

• TG_DEPENDENCIES

--external

Discover external dependencies from initial results.

Controls whether Terragrunt should discover and include external dependencies in the list results. External dependencies are Terragrunt configurations that are referenced by your configurations but exist outside the current working directory.

This flag is most useful when:

• Investigating the complete dependency graph of your infrastructure
• Determining the full blast radius of a change

Example:

$ terragrunt list -l --dependencies
Type  Path          Dependencies
unit  a-dependent   b-dependency
unit  b-dependency

$ terragrunt list -l --dependencies --external
Type  Path                      Dependencies
unit  ../external/c-dependency
unit  a-dependent               ../external/c-dependency, b-dependency
unit  b-dependency

Note

The --external flag is typically used in combination with --dependencies to show why the external dependency was discovered.

Type: boolean

Environment Variables:

• TG_EXTERNAL

--tree

Output in tree format.

A shorthand flag that sets --format=tree. Displays the list results in a hierarchical tree structure that shows the relationships between your Terragrunt configurations.

Type: boolean

Aliases:

• -T

Environment Variables:

• TG_TREE

--long

Output in long format.

A shorthand flag that sets --format=long. Displays the list results in a detailed tabular format that includes additional information about each configuration.

Type: boolean

Aliases:

• -l

Environment Variables:

• TG_LONG

--dag

Output in DAG mode.

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

Examples:

By default, configurations are sorted alphabetically:

$ terragrunt list
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 list --dag
live/dev/vpc   live/prod/vpc  live/dev/db
live/prod/db   live/dev/ec2   live/prod/ec2

When not used in the long format:

$ terragrunt list -l --dependencies
Type  Path           Dependencies
unit  live/dev/db    live/dev/vpc
unit  live/dev/ec2   live/dev/db, live/dev/vpc
unit  live/dev/vpc
unit  live/prod/db   live/prod/vpc
unit  live/prod/ec2  live/prod/db, live/prod/vpc
unit  live/prod/vpc

Results are sorted by name.

When combined with the long format:

$ terragrunt list -l --dependencies --dag
Type  Path           Dependencies
unit  live/dev/vpc
unit  live/prod/vpc
unit  live/dev/db    live/dev/vpc
unit  live/prod/db   live/prod/vpc
unit  live/dev/ec2   live/dev/db, live/dev/vpc
unit  live/prod/ec2  live/prod/db, live/prod/vpc

When not used in the tree format:

$ terragrunt list -T
.
╰── live
    ├── dev
    │   ├── db
    │   ├── ec2
    │   ╰── vpc
    ╰── prod
        ├── db
        ├── ec2
        ╰── vpc

When combined with the tree format:

$ terragrunt list -T --dag
.
├── live/dev/vpc
│   ├── live/dev/db
│   │   ╰── live/dev/ec2
│   ╰── live/dev/ec2
╰── live/prod/vpc
    ├── live/prod/db
    │   ╰── live/prod/ec2
    ╰── live/prod/ec2

Type: boolean

Environment Variables:

• TG_DAG

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