Terraform State Commands

The state file works like a ledger. It records every resource Terraform manages and the real-world ID behind each one. Editing that ledger by hand risks corruption, so Terraform ships a set of terraform state commands for safe changes. These commands inspect, rename, and remove records. None of them touches real infrastructure, which makes them gentle tools for housekeeping.

What State Commands Touch

State commands change the ledger only. Your servers, buckets, and networks stay exactly as they are.

Diagram: Ledger Versus Real World

  +-------------------+        +----------------------+
  |  Your .tf files   |        |   Real cloud account |
  +---------+---------+        +-----------+----------+
            |                              |
            |      +---------------+       |
            +----->|  State file   |<------+
                   |   (ledger)    |
                   +-------+-------+
                           ^
                           |
             terraform state commands edit this box only

List Everything: terraform state list

The list command prints the address of every resource in the state.

terraform state list

aws_instance.web
aws_s3_bucket.logs
module.network.aws_vpc.main

Add a filter to narrow the output.

terraform state list aws_instance

Inspect One Item: terraform state show

The show command prints every recorded attribute of a single resource.

terraform state show aws_instance.web

Use it to find an ID, an IP address, or a setting without opening the raw file.

Rename or Move: terraform state mv

Suppose you rename a resource in code from web to app. Terraform sees an old resource that vanished and a new resource that appeared. Without help, it destroys the old server and builds a new one. The move command updates the ledger so Terraform recognizes the same server under the new name.

terraform state mv aws_instance.web aws_instance.app

Moving Into a Module

terraform state mv aws_instance.web module.compute.aws_instance.web

Run the move command first. Rename the resource in code second. A follow-up terraform plan should show no changes.

The Modern Alternative: Moved Blocks

Newer Terraform versions record renames inside the code with a moved block. Teammates and pipelines then apply the rename automatically.

moved {
  from = aws_instance.web
  to   = aws_instance.app
}

Forget a Resource: terraform state rm

The remove command deletes a record from the ledger. Terraform stops managing that resource, and the real resource keeps running.

terraform state rm aws_s3_bucket.legacy

Use it when another team takes ownership of a resource or when you plan to import it into a different configuration. Delete the matching block from your code too. A leftover block makes Terraform try to create the resource again.

Download the State: terraform state pull

The pull command prints the current state as JSON. It works with remote backends too.

terraform state pull > backup.tfstate

Take a backup before any risky change.

Upload the State: terraform state push

The push command overwrites the remote state with a local file. Treat it as a last-resort tool. A wrong push replaces the truth with an older copy. Pull a fresh backup first and confirm nobody else is running Terraform.

Replace a Resource: terraform apply -replace

A resource sometimes misbehaves and needs a rebuild. The replace option marks one resource for destroy and create during the next apply.

terraform apply -replace="aws_instance.web"

This option replaces the older terraform taint command.

Command Summary

CommandWhat It DoesRisk Level
state listShows all resource addressesNone
state showShows one resource in detailNone
state pullDownloads the stateNone
state mvRenames or moves a recordLow
state rmRemoves a recordMedium
state pushUploads a state fileHigh

Safety Habits

  • Pull a backup before every mv, rm, or push.
  • Run terraform plan after each change and confirm it shows no surprises.
  • Coordinate with teammates so nobody applies during the edit.
  • Never open and edit the raw state file in a text editor.

Key Points

  • State commands edit the ledger and leave real infrastructure alone.
  • state list and state show inspect resources safely.
  • state mv preserves a resource after a rename or a move into a module.
  • state rm makes Terraform forget a resource without deleting it.
  • state pull creates backups, and state push needs extreme care.
  • moved blocks and apply -replace cover the modern workflows.