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

Generate a DOT format graph of dependencies for visualization.

$ terragrunt list --format=dot --dependencies
digraph {
  "live/dev/vpc" ;
  "live/dev/db" ;
  "live/dev/ec2" ;
  "live/dev/db" -> "live/dev/vpc";
  "live/dev/ec2" -> "live/dev/db";
  "live/dev/ec2" -> "live/dev/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

DOT Format

The DOT format outputs a directed acyclic graph (DAG) in DOT language format, which can be rendered as a visual dependency graph using tools like GraphViz.

$ terragrunt list --format=dot --dependencies
digraph {
  "live/dev/vpc" ;
  "live/dev/db" ;
  "live/dev/ec2" ;
  "live/dev/db" -> "live/dev/vpc";
  "live/dev/ec2" -> "live/dev/db";
  "live/dev/ec2" -> "live/dev/vpc";
  "live/prod/vpc" ;
  "live/prod/db" ;
  "live/prod/ec2" ;
  "live/prod/db" -> "live/prod/vpc";
  "live/prod/ec2" -> "live/prod/db";
  "live/prod/ec2" -> "live/prod/vpc";
}

You can render the DOT output to an image using GraphViz:

$ terragrunt list --format=dot --dependencies | dot -Tpng > graph.png
$ terragrunt list --format=dot --dependencies | dot -Tsvg > graph.svg

DOT Format Alias

The dag graph command is an alias for list --format=dot. Both commands produce identical DOT format output:

terragrunt dag graph
# Equivalent to:
terragrunt list --format=dot --dependencies --external

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.

Automatic Dependency Discovery

The --external flag automatically enables dependency discovery, so you don’t need to explicitly pass --dependencies when using --external. The following commands are equivalent:

terragrunt list --external
terragrunt list --dependencies --external

This is because the default text format of list won’t display dependency information anyways (as opposed to the long format, which does).

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.

Filtering Results

Experimental Feature

This feature is currently experimental and not yet complete. See the filter-flag experiment documentation for details on what is and isn’t supported.

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

terragrunt list --experiment filter-flag --filter 'foo'

The list command supports the --filter flag to target specific configurations using a flexible query language. This is particularly useful for listing configurations that match specific criteria before running operations on them.

Basic Filtering Examples

# Filter by name using glob patterns
terragrunt list --experiment filter-flag --filter 'app*'

# Filter by path
terragrunt list --experiment filter-flag --filter './prod/**'

# Filter by type
terragrunt list --experiment filter-flag --filter 'type=unit'

# Combine filters with intersection
terragrunt list --experiment filter-flag --filter './prod/** | type=unit'

Advanced Filtering

The filter syntax supports negation, multiple filters, and complex queries:

# Exclude specific configurations
terragrunt list --experiment filter-flag --filter '!./test/**'

# Multiple filters (OR logic)
terragrunt list --experiment filter-flag --filter 'app1' --filter 'app2'

# Complex queries with chaining
terragrunt list --experiment filter-flag --filter './dev/** | type=unit | !name=unit1'

Learn More About Filtering

For comprehensive examples and advanced usage patterns, see the Filters feature documentation.

Flags

--format

Format the results as specified. Supported values (text, long, tree, dot). 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.
• dot: Output in DOT format for visualization. Generates a graph using the GraphViz DOT language. Ideal for creating visual dependency graphs.

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

# DOT format - Useful for visualizing dependency graphs
$ terragrunt list --format=dot --dependencies
digraph {
  "live/dev/vpc" ;
  "live/dev/db" ;
  "live/dev/ec2" ;
  "live/dev/db" -> "live/dev/vpc";
  "live/dev/ec2" -> "live/dev/db";
  "live/dev/ec2" -> "live/dev/vpc";
  "live/prod/vpc" ;
  "live/prod/db" ;
  "live/prod/ec2" ;
  "live/prod/db" -> "live/prod/vpc";
  "live/prod/ec2" -> "live/prod/db";
  "live/prod/ec2" -> "live/prod/vpc";
}

# Render the DOT output to an image using GraphViz
$ terragrunt list --format=dot | dot -Tpng > graph.png

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.

DOT Format Alias

The dag graph command is an alias for list --format=dot. Both commands produce identical DOT format output:

terragrunt dag graph
# Equivalent to:
terragrunt list --format=dot --dependencies --external

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

--filter

Filter configurations using a flexible query language

Experimental Feature

This feature is currently experimental and not yet complete. See the filter-flag experiment documentation for details on what is and isn’t supported.

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

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

Examples below will omit the --experiment filter-flag flag for brevity.

The --filter flag provides a sophisticated querying syntax for targeting specific units and stacks in Terragrunt commands.

Usage

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:

# Exact match
terragrunt find --filter app1

# Glob pattern
terragrunt find --filter 'app*'

Path-Based Filtering

Match configurations by their file system path:

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

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

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 for more information on how Terragrunt tracks files that are read during parsing.

Negation

Exclude configurations using the ! prefix:

# Exclude by name
terragrunt find --filter '!app1'

# Exclude by path
terragrunt find --filter '!./prod/**'

Intersection (Refinement)

Use the | operator to refine results:

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

# Find components named 'unit1' OR 'stack1'
terragrunt find --filter unit1 --filter stack1

Supported Commands

Currently supported in:

• find
• list
• run
• hcl fmt
• hcl validate

Planned for future releases:

• dag graph

Learn More

For comprehensive examples and advanced usage patterns, see the Filters feature documentation.

Type: list(string)