In this article, we’ll show you how to use it with a few practical examples.
What is terraform state pull?
terraform state pull downloads the current Terraform state from its current location, upgrades it to a format compatible with the Terraform version you're running locally, and prints the raw state JSON to standard output (stdout). It does not write any changes back to the state backend.
The syntax is:
terraform state pull
There are no positional arguments and no pull-specific flags. The command’s behavior is driven by:
- The working directory you run it from
- Your configured backend
- The currently selected workspace
You can still use Terraform’s global options before the subcommand, like -chdir=DIR, to run the command against a different root module directory without changing folders.
This is especially handy when you need to read values directly out of state or when you want a backup copy before doing any manual state work. Terraform backends let the terraform state subcommands operate as if the state were local, even when it’s stored remotely.
What will you see in the pulled state?
Here’s a simple Terraform resource:
resource "aws_s3_bucket" "logs" { bucket = "acme-prod-logs-1234" }
After you apply it, terraform state pull will include a JSON entry for that managed resource. The full file is larger, but the shape typically looks like this:
{ "resources": [ { "mode": "managed", "type": "aws_s3_bucket", "name": "logs", "instances": [ { "attributes": { "bucket": "acme-prod-logs-1234", "id": "acme-prod-logs-1234" } } ] } ] }
Terraform uses this state data to map real-world objects back to resource instances in your configuration, track metadata, and decide what changes to make next.
You'll also see top-level metadata and extra fields on resources. The exact JSON shape can vary by Terraform version, provider, and resource.
Note that terraform state pull can include sensitive values because state often contains resource attributes and metadata. Treat the output like a secret: keep it out of Git, store backups securely, and avoid pasting state into tickets or chat. Even if an output or variable is marked sensitive, the underlying value can still end up in state, so keep state locked down.
Example 1: Save the current state to a file as a backup
This is the simplest, most common use of terraform state pull. After you have run terraform init at least once to set up your backend, terraform state pull fetches the latest state snapshot and prints it as JSON.
terraform init terraform state pull > state-backup.tfstate
Redirecting the output into state-backup.tfstate gives you a point-in-time backup you can store securely, which is helpful before risky refactors like moving modules, changing resource addresses, or running imports.
This works whether your backend is local or remote because the command always pulls from the “current location” configured for the directory. Terraform upgrades the downloaded copy to the latest compatible state format as it outputs it, so the file you save reflects what your current Terraform version understands.
Example 2: Pull state and extract a single value with jq
When your state is stored in a remote backend, terraform state pull streams the raw JSON state to stdout, and jq can extract just the value you care about, such as an output named vpc_id.
If you only need an output value, you can often use terraform output instead of reading state directly.
terraform init terraform state pull | jq -r '.outputs.vpc_id.value'
This is useful when an unexpected terraform plan makes you want to confirm what Terraform believes is deployed without clicking through a UI or downloading state by hand.
It’s also a good fit for automation and incident response because you can reduce the output to a single line that’s easy to compare across environments.
Example 3: Pull state snapshots from two environments and diff them
Here, terraform state pull acts as a snapshot tool. You pull state from one working directory, pull state from another, and diff the two JSON files to spot differences in resource attributes, counts, or outputs.
Some differences are just metadata, like serial, so it helps to sort the JSON and remove common metadata fields before diffing.
terraform -chdir=infra/dev init terraform -chdir=infra/dev state pull | jq -S 'del(.serial,.lineage,.terraform_version)' > /tmp/dev.tfstate.json terraform -chdir=infra/prod init terraform -chdir=infra/prod state pull | jq -S 'del(.serial,.lineage,.terraform_version)' > /tmp/prod.tfstate.json diff -u /tmp/dev.tfstate.json /tmp/prod.tfstate.json | head
This is especially helpful when dev and prod are meant to be similar but plans are diverging, or when you suspect a backend or workspace mismatch. Since terraform state pull always pulls from the backend configured in the directory you run it from, this workflow compares the state Terraform has recorded for each environment.
Key points
Used carefully, terraform state pull is a simple way to inspect and snapshot Terraform state without changing anything. Keep the output secure because state may include sensitive data, and you’ll have a reliable tool for debugging and validation across environments.
If you want tighter guardrails around Terraform workflows, use a purpose-built orchestration platform instead of relying on ad hoc scripts. Spacelift helps you run Terraform in a controlled workflow with policy as code, audit trails, and self-service patterns, so teams can move quickly without losing governance.
- Policy as code (powered by Open Policy Agent)
- Multi-IaC workflows
- Self-service infrastructure
- Integrations with third-party tools
If you want to learn more, create a free account or book a demo.
Note: HashiCorp changed Terraform’s license for newer releases, while earlier versions remain under their previous open-source license. OpenTofu is an open-source fork based on Terraform 1.5.6 and is a viable alternative for teams that want a community-governed option.