terraform console: Interactive Exploration

terraform console is a read-evaluate-print loop for HCL expressions. It loads the same configuration and state that plan and apply use, then accepts expressions on stdin and prints the evaluated result on stdout. It is the fastest way to verify that a complex for expression or a function call produces the value you expect — before you commit the configuration that depends on it.

What console is

terraform console starts an interactive REPL. The prompt is >; you type an expression, press Enter, and the CLI prints the result:

$ terraform console
> length(["a", "b", "c"])
3
> upper("hello")
"HELLO"
> aws_vpc.main.cidr_block
"10.0.0.0/16"
> aws_instance.web[0].public_ip
"54.123.45.67"
> [for s in aws_subnet.private : s.id]
[
  "subnet-0abc123",
  "subnet-0def456",
  "subnet-0ghi789",
]
> exit

Console reads from the current state file. The expressions have access to:

• Every resource address in the configuration (aws_vpc.main, aws_subnet.private[0], etc.)
• Every variable value (from the configuration defaults, the environment, or .tfvars files)
• Every local value
• Every output value
• The full HCL function library

Console does not have access to anything plan produces after a refresh; it reads the state as it was at the end of the last apply (or refresh). If a resource attribute has changed in the real world but state has not been refreshed, console returns the stale value.

When to use console

Console is for expression debugging, not for resource manipulation. The four cases where it earns its place:

1. Verifying a complex for expression. A common pattern is to project a list of resources into a map of attributes:

# You want to verify this expression produces what you expect.
locals {
  subnet_by_az = {
    for s in aws_subnet.private :
    s.availability_zone => s.id
  }
}

In console:

> {for s in aws_subnet.private : s.availability_zone => s.id}
{
  "us-east-1a" = "subnet-0abc123"
  "us-east-1b" = "subnet-0def456"
  "us-east-1c" = "subnet-0ghi789"
}

The expression is verified in seconds. The alternative — running plan, reading the output, and scrolling — is slower and noisier.

2. Testing a function chain. Some expressions involve three or four function calls in a row. Console lets you test each step:

> cidrsubnet("10.0.0.0/16", 8, 5)
"10.0.5.0/24"
> cidrsubnet("10.0.0.0/16", 8, 5 + 2)
"10.0.7.0/24"
> [for i in range(3) : cidrsubnet("10.0.0.0/16", 8, i)]
[
  "10.0.0.0/24",
  "10.0.1.0/24",
  "10.0.2.0/24",
]

3. Inspecting a value that plan output truncates. When plan prints a long string (an IAM policy document, a user-data script), console lets you see the full value:

> aws_instance.web.user_data
"#!/bin/bash\necho 'Deploying...'\napt-get update\n..."

4. Debugging a count or for_each expression. When the iteration logic is wrong, console helps isolate which element of the iteration is failing:

> [for i, s in aws_subnet.private : i]
[
  0,
  1,
  2,
]
> aws_subnet.private[1].cidr_block
"10.0.1.0/24"

Passing variables and options

# Default: read variables from the configuration and any .tfvars files.
terraform console

# Pass a variable on the command line.
terraform console -var="environment=production"

# Pass a tfvars file.
terraform console -var-file=production.tfvars

# Read expressions from a file, non-interactively.
terraform console < expressions.hcl

The non-interactive form is useful for scripted debugging sessions: write a list of expressions to a file, pipe it into console, capture the output. The output is the same JSON-like form that plan emits, suitable for parsing with jq.

cat <<'EOF' | terraform console
> length(aws_subnet.private)
> aws_subnet.private[0].availability_zone
> cidrsubnet(aws_vpc.main.cidr_block, 8, 10)
> EOF
3
"us-east-1a"
"10.0.10.0/24"

The limit: console cannot mutate state

Console evaluates expressions and prints results. It does not:

• Write to the state file.
• Call provider APIs for side effects (no aws s3 cp, no terraform apply for a single resource).
• Trigger a refresh.
• Persist any change you make.

A common misuse is to reach for console as a way to “test” a configuration change. It does not test apply. It evaluates expressions. A configuration that evaluates correctly in console can still fail in apply because of an IAM permission, an invalid argument, or a provider-side constraint.

Production failure modes

1. Using console to mutate state. Symptom: the operator tries to “modify” a resource attribute from the console prompt, expecting the state file to update. The CLI prints the new value but the state file is unchanged. Cause: console evaluates expressions; it does not write state. Recovery: exit console; use terraform state subcommands or modify the configuration and apply.

2. Console fails to start because of an init issue. Symptom: terraform console exits with “Backend reinitialisation required” or “Provider plugin not found”. Cause: the working directory has not been initialised, or the lockfile has drifted. Recovery: run terraform init first.

3. Expression returns a stale value. Symptom: the operator expects a resource attribute that has changed in the cloud to be reflected in console. It is not. Cause: console reads state as of the last apply or refresh. If the cloud has changed since then, the console value is stale. Recovery: exit console, run terraform plan -refresh-only, then re-enter console. Or run terraform refresh (deprecated, prefer -refresh-only) and then console.

4. Type error from a function on a wrong-typed argument. Symptom: Error: Invalid value for tfvars parameter or Invalid function argument. Cause: the expression passed an argument of the wrong type (e.g., a number where a string is expected). Recovery: read the function documentation; cast the value explicitly (tostring(), tonumber(), tolist()).

5. Console session left open in CI. Symptom: a CI job hangs because console is waiting for stdin that never arrives. Cause: the job invoked terraform console without piping input or using -var. Recovery: use the non-interactive form < expressions.hcl or pass all variables via flags. Never invoke console from CI without piping input.

6. Difference between console evaluation and apply evaluation. Symptom: an expression that evaluates correctly in console produces a different value in plan or apply. Cause: rare, but possible — the configuration has changed since the last apply, or the state has drifted. Recovery: this is not a console bug. Refresh state and re-evaluate.

Security implications

Console reads from the state file. Any process that can run terraform console in a working directory can read every output value and every resource attribute, including sensitive outputs. Mitigations:

• Limit who can run console in production working directories. The IAM role that grants terraform plan also grants terraform console.
• Treat console sessions as privileged: they reveal the state of every resource, including endpoints, ARNs, and IDs.
• Console logs (if any) should not be retained beyond the debug session.

Console does not call provider APIs, so it does not consume the API quota and does not appear in CloudTrail. This makes it useful for low-visibility debugging but also means the activity is not audited.

Performance implications

Console reads the state file once at start, then evaluates expressions in memory. There is no network call per expression (the state was already loaded). Startup time is dominated by the state read: a few hundred milliseconds for a local state file, a few hundred milliseconds to a few seconds for a remote backend (S3, GCS, Terraform Cloud).

Expressions that traverse large resource graphs (e.g., [for r in aws_instance.all : r.private_ip]) are slower because they materialise the entire list. For a configuration with 10,000 instances, the materialisation takes seconds.

Verification

# Verify console starts and accepts a basic expression.
echo '1 + 1' | terraform console
# Expect: 2

# Verify console reads a resource from state.
echo 'aws_vpc.main.cidr_block' | terraform console
# Expect: "10.0.0.0/16" (or whatever the state contains)

# Verify console handles a function call.
echo 'length(aws_subnet.private)' | terraform console
# Expect: a number

# Verify -var is respected.
echo 'var.environment' | terraform console -var="environment=production"
# Expect: "production"

A healthy console workflow leaves the state file unchanged, returns the expected values, and does not log sensitive outputs to disk.

What comes next

The V-Workflow module ends here. The next module covers the state file: where it lives, how it is structured, how it is locked, and how to recover from corruption. Console is the last command in the workflow; the state file is the artefact every command reads and writes.