output

Usage

The `terragrunt stack output` command allows users to retrieve and interact with outputs from multiple units within a Terragrunt stack.

This feature simplifies handling infrastructure outputs by consolidating them into a single view.

Examples

Get outputs from a stack of units.

terragrunt stack output

Get outputs from a stack of units in JSON format.

terragrunt stack output --format json

Get an output from a stack of units in raw format.

terragrunt stack output --format raw app.id

Executing terragrunt stack output in a stack directory produces an aggregated output from all units within the stack:

$ terragrunt stack output
service.output1 = "output1"
service.output2 = "output2"
db.output1 = "output1"
db.output2 = "output2"

Indexing outputs

To retrieve outputs for a specific unit, specify the unit name:

$ terragrunt stack output project1_app1
project1_app1 = {
  complex = {
    delta     = 0.02
    id        = 2
    name      = "name1"
    timestamp = "2025-02-07T21:05:51Z"
  }
  complex_list = [{
    delta     = 0.02
    id        = 10
    name      = "name1"
    timestamp = "2025-02-07T21:05:51Z"
    }, {
    delta     = 0.03
    id        = 20
    name      = "name10"
    timestamp = "2025-02-07T21:05:51Z"
  }]
  custom_value1 = "value1"
  data          = "app1"
  list          = ["1", "2", "3"]
}

You can also retrieve a specific output from a unit:

$ terragrunt stack output project1_app1.custom_value1
project1_app1.custom_value1 = "value1"

Output formats

Terragrunt provides multiple output formats for easier parsing and integration with other tools. The desired format can be specified using the --format CLI flag.

Format	Description
default	Format output as HCL.
json	Format output as JSON. This can be useful for integrations with other tools.
raw	Format output as a simple raw string. Useful for integration into bash scripts.

To retrieve outputs in structured JSON format:

$ terragrunt stack output --format json project1_app2
{
  "project1_app2": {
    "complex": {
      "delta": 0.02,
      "id": 2,
      "name": "name2",
      "timestamp": "2025-02-07T21:05:51Z"
    },
    "complex_list": [
      {
        "delta": 0.02,
        "id": 2,
        "name": "name2",
        "timestamp": "2025-02-07T21:05:51Z"
      },
      {
        "delta": 0.03,
        "id": 2,
        "name": "name3",
        "timestamp": "2025-02-07T21:05:51Z"
      }
    ],
    "custom_value2": "value2",
    "data": "app2",
    "list": [
      "a",
      "b",
      "c"
    ]
  }
}

json format

Accessing a specific list inside JSON format:

$ terragrunt stack output --format json project1_app2.complex_list
{
  "project1_app2.complex_list": [
    {
      "delta": 0.02,
      "id": 2,
      "name": "name2",
      "timestamp": "2025-02-07T21:05:51Z"
    },
    {
      "delta": 0.03,
      "id": 2,
      "name": "name3",
      "timestamp": "2025-02-07T21:05:51Z"
    }
  ]
}

raw format

The raw format returns outputs as plain values without additional structure. When accessing lists or structured outputs, indexes are required to extract values.

Retrieving a simple value:

$ terragrunt stack output --format raw project1_app2.data
app2

Flags

--format

Format stack output. (json, raw).

Specifies the output format for stack outputs. Available formats are:

• default - Format output as HCL (default)
• json - Format output as JSON for machine readability
• raw - Format output as raw string for shell script integration

Format	Description
default	Format output as HCL.
json	Format output as JSON. This can be useful for integrations with other tools.
raw	Format output as a simple raw string. Useful for integration into bash scripts.

Example:

# JSON format
terragrunt stack output --format json

# Raw format
terragrunt stack output --format raw project1_app1.custom_value1

json format

To retrieve outputs in structured JSON format:

$ terragrunt stack output --format json project1_app2
{
  "project1_app2": {
    "complex": {
      "delta": 0.02,
      "id": 2,
      "name": "name2",
      "timestamp": "2025-02-07T21:05:51Z"
    },
    "custom_value2": "value2",
    "data": "app2",
    "list": [
      "a",
      "b",
      "c"
    ]
  }
}

Accessing a specific list inside JSON format:

$ terragrunt stack output --format json project1_app2.complex_list
{
  "project1_app2.complex_list": [
    {
      "delta": 0.02,
      "id": 2,
      "name": "name2",
      "timestamp": "2025-02-07T21:05:51Z"
    },
    {
      "delta": 0.03,
      "id": 2,
      "name": "name3",
      "timestamp": "2025-02-07T21:05:51Z"
    }
  ]
}

raw format

The raw format returns outputs as plain values without additional structure. When accessing lists or structured outputs, indexes are required to extract values.

Retrieving a simple value:

$ terragrunt stack output --format raw project1_app2.data
app2

Type: string

Environment Variables:

• TG_FORMAT

--json

Format stack output as JSON. Alias for --format json.

A convenience flag that formats the stack output as JSON. This is equivalent to using --format json.

Example:

terragrunt stack output --json

Type: bool

Environment Variables:

• TG_JSON

--raw

Format stack output as raw string. Alias for --format raw.

A convenience flag that formats the stack output as a raw string. This is equivalent to using --format raw.

This is particularly useful when you need to use the output in shell scripts or other automation.

Example:

# Store the output in a variable
APP_ID=$(terragrunt stack output --raw app.id)

Caution

When using --stack-output-raw, you must use index-based access. Attempting to access nested structures directly may result in unexpected output or errors.

Type: bool

Environment Variables:

• TG_RAW

--no-stack-generate

Disable automatic stack regeneration before running the stack commands.

When enabled, Terragrunt will skip automatic stack regeneration before executing the command. This is useful when you want to run operations using the existing .terragrunt-stack directory without regenerating it, improving execution speed and avoiding unnecessary changes.

Type: bool

Environment Variables:

• TG_NO_STACK_GENERATE

--discovery-boundary

Directory that encloses graph discovery for filters, instead of the git repository root

Experimental

This flag is gated behind the bounded-discovery experiment. Enable it with --experiment=bounded-discovery (or TG_EXPERIMENT=bounded-discovery); otherwise setting --discovery-boundary returns an error. The flag’s behavior may change while the experiment is in progress.

Filter expressions that traverse the dependency graph reach beyond the working directory. Dependents (...{unit}) can live anywhere, so Terragrunt searches from the working directory up to the git repository root; dependencies ({unit}...) are declared by path and can point anywhere.

The --discovery-boundary flag is a single enclosure for that traversal: it replaces the git repository root as the outer limit, and a configuration that traversal reaches outside it is not returned, so find does not list it and run --all does not run it. Configurations inside the boundary are discovered as usual.

The boundary decides which configurations a command acts on, not which ones Terragrunt may read. A unit inside the boundary can declare a dependency outside it, and that dependency is still read and parsed: Terragrunt needs its configuration to fetch the outputs the dependent unit consumes, and it needs the dependency edge to order the units that do run. What the boundary withholds is the unit itself, which is left for a separate run to apply, the same way a dependency outside the working directory is treated today.

This matters in monorepos where environments are isolated from each other. When sibling environments cannot be parsed independently, the default search fails or wastes work reaching into them:

environments/
  staging/
  production/
  test/
  root.hcl

Bounding the traversal to the current environment keeps discovery inside it:

cd environments/staging
terragrunt find --experiment bounded-discovery --filter '...{vpc}' --discovery-boundary .

Usage

# Enclose discovery within the working directory
terragrunt find --filter '...{vpc}' --discovery-boundary .

# Enclose discovery within a parent directory
terragrunt run --all plan --filter '...{vpc}' --discovery-boundary ..

# Equivalent, via environment variable
TG_DISCOVERY_BOUNDARY=. terragrunt find --filter '...{vpc}'

# From the repository root, keep app's dependencies within prod
terragrunt find --filter '{./prod/app}...' --discovery-boundary ./prod

The boundary must be an existing directory. Relative paths are resolved against the working directory.

The boundary applies to what traversal reaches, so a command that names no filter keeps every configuration under the working directory even when the boundary sits below it. Narrow the working directory itself, with --working-dir, to change where discovery starts.

Where the boundary may sit depends on the directions the filters traverse. Dependent traversal searches upward from the working directory, so a boundary that excludes the working directory could never take effect; filters that traverse dependents require the boundary to be the working directory or one of its parents. Dependency traversal follows declared paths outward from the units a filter matched and never consults the working directory, so filters that traverse only dependencies accept any directory, including one below the working directory. That is the same rule the inline (dir) operand follows.

Type: string

Environment Variables:

• TG_DISCOVERY_BOUNDARY