Terraform State Commands Explained with Examples

Terraform State Commands help you interact with the Terraform state file without editing the underlying JSON directly.

Sooner or later, every Terraform user encounters a situation where the state file needs attention. You may need to rename a resource, inspect tracked infrastructure, remove a resource from state management, or troubleshoot unexpected Terraform behavior.

Understanding Terraform state commands helps you make these changes safely while avoiding accidental resource recreation and infrastructure drift.

If you're new to Terraform state, start with our guides on Terraform State and Purpose of State in Terraform before diving into state operations.

Why Terraform State Commands Matter in Real Projects

Terraform uses a state file to keep track of infrastructure resources that it manages.

The state file allows Terraform to:

• Track real infrastructure resources.
• Understand resource dependencies.
• Compare current infrastructure against configuration.
• Improve performance during terraform plan and terraform apply.

By default, Terraform stores state in a local file called terraform.tfstate.

For teams and production environments, local state quickly becomes difficult to manage. Using Remote State and State Locking in Terraform helps prevent concurrent updates and state corruption.

For AWS-based backends, see our guide on Remote Backends with AWS S3.

What Are Terraform State Commands?

Terraform provides the terraform state command to safely inspect and manipulate the state file.

Instead of manually editing the state file, which can easily introduce inconsistencies, use the supported state subcommands.

terraform state <subcommand> [options]

These commands are part of the official Terraform CLI documented by HashiCorp Terraform.

Before learning individual state commands, it can also help to understand other commonly used Terraform Commands.

Common Terraform State Commands at a Glance

The most frequently used Terraform state commands are:

• terraform state list
• terraform state show
• terraform state mv
• terraform state rm
• terraform state pull

Each command solves a specific state management problem without requiring direct modification of the state file.

List Resources with terraform state list

The terraform state list command displays all resource addresses currently tracked in the state file.

terraform state list

Example output:

aws_s3_bucket.logs
aws_dynamodb_table.state_lock
aws_iam_role.application_role

You can also filter resources using an address pattern.

terraform state list aws_s3_bucket.*

This command is useful when:

• Auditing infrastructure.
• Verifying imported resources.
• Confirming resource addresses before running other state commands.

View Resource Details with terraform state show

The terraform state show command displays the attributes of a specific resource stored in the state.

terraform state show aws_s3_bucket.logs

Typical information includes:

• Resource ID
• Tags
• Region
• ARN
• Provider-specific attributes

This command is commonly used during troubleshooting when you need to understand Terraform's view of a resource.

For debugging workflows, you may also find our guide on Debugging in Terraform useful.

Rename or Move Resources with terraform state mv

The terraform state mv command moves or renames resources within the state file.

This is one of the most valuable commands when refactoring Terraform code.

Rename a Resource Without Recreating It

Suppose you originally defined an S3 bucket like this:

resource "aws_s3_bucket" "logs" {
  bucket = "company-logs-bucket"
}

You later decide to rename the resource block:

resource "aws_s3_bucket" "application_logs" {
  bucket = "company-logs-bucket"
}

Without updating the state, Terraform may think the old resource was deleted and a new one should be created.

To avoid that, move the state entry:

terraform state mv \
aws_s3_bucket.logs \
aws_s3_bucket.application_logs

Run a plan afterward:

terraform plan

If everything was done correctly, Terraform should show no infrastructure changes.

Pro Tip

Before running terraform state mv, create a backup of the state file and verify the source and destination resource addresses carefully.

A typo can cause Terraform to lose track of resources and generate an unexpected execution plan.

Pull Remote State with terraform state pull

When using remote backends, the state file is stored outside your local machine.

The terraform state pull command retrieves the latest state from the configured backend.

terraform state pull

The command outputs the state file in JSON format.

You can combine it with tools such as jq to inspect specific resources.

terraform state pull | jq '.resources[] | select(.type=="aws_dynamodb_table")'

This is particularly useful when:

• Auditing infrastructure.
• Troubleshooting remote state issues.
• Building automation around Terraform state.

Remove Resources from State with terraform state rm

The terraform state rm command removes a resource from Terraform state without deleting the actual infrastructure.

terraform state rm aws_s3_bucket.logs

After running this command:

• The resource still exists in your cloud provider.
• Terraform stops tracking it.
• Future plans no longer include the resource unless it is imported again.

This command is often used during:

• Infrastructure migrations.
• State cleanup.
• Resource ownership transfers.
• Refactoring projects.

After removing the resource from state, remove the corresponding Terraform configuration if Terraform should no longer manage it.

If you later want Terraform to manage the resource again, use Terraform Import to re-associate it with state.

Common Real-World Uses of Terraform State Commands

Terraform state commands become valuable in several practical situations.

Refactoring Terraform Code

When restructuring modules or renaming resources, terraform state mv helps preserve existing infrastructure.

For larger projects, see our guides on:

• Modules in Terraform
• Creating and Using Modules in Terraform
• Using Modules from Terraform Registry

Infrastructure Audits

Commands such as terraform state list, terraform state show, and terraform state pull help verify what Terraform is actually tracking.

Resource Migration

When moving resources between configurations, accounts, or workspaces, state commands help maintain consistency.

You may also want to review Terraform Workspaces.

Recovering from State Issues

State commands are frequently used during troubleshooting when Terraform's state no longer matches actual infrastructure.

Understanding Terraform State Considerations can help reduce these problems.

Best Practices for Terraform State Management

Follow these practices whenever working with Terraform state commands.

Never Edit the State File Manually

Terraform provides supported commands for state manipulation.

Directly editing the JSON file increases the risk of state corruption and infrastructure inconsistencies.

Always Create a Backup

Create a backup before making state changes.

If you're using an S3 backend, enable bucket versioning so previous state versions can be recovered.

Run terraform plan After State Changes

Always verify the impact of state modifications.

terraform plan

This helps catch unexpected changes before they reach production.

Use Remote State in Team Environments

Remote state storage improves collaboration and reduces operational risk.

HashiCorp recommends using supported backends rather than sharing local state files.

You can review available backend options in the official Terraform Backend Documentation.

Minimize Manual State Operations

State commands are powerful but should be used only when necessary.

Most infrastructure workflows should continue to rely on standard Terraform configuration changes and applies.

Conclusion

Terraform State Commands provide safe ways to inspect, move, rename, and remove resources from Terraform state.

Commands such as state list, state show, state mv, state pull, and state rm are commonly used during infrastructure refactoring, migrations, audits, and troubleshooting.

When combined with remote state storage, locking, backups, and careful planning, these commands give you precise control over Terraform-managed infrastructure without risking unnecessary resource recreation.

For additional Terraform learning, explore the official Terraform Documentation and the Terraform Registry.

Frequently Asked Questions (FAQs)

Can I edit the Terraform state file manually?

No. Direct modification is not recommended.

Use supported Terraform state commands to safely manipulate state and avoid introducing inconsistencies.

What happens when I use terraform state rm?

Terraform removes the resource from state tracking but does not delete the actual infrastructure resource.

The resource continues to exist in the cloud provider.

Is terraform state mv destructive?

No.

When used correctly, terraform state mv only updates resource addresses in the state file and does not recreate infrastructure resources.

How do I view Terraform state stored in a remote backend?

Use:

terraform state pull

This retrieves the current state from the configured backend and outputs it in JSON format.

When should I use terraform state show?

Use it when you need to inspect the attributes of a specific resource tracked by Terraform.

It is particularly useful for troubleshooting, auditing, and validating resource configuration.

Which Terraform state command is used most often?

Most engineers frequently use:

• terraform state list
• terraform state show
• terraform state mv

These commands help inspect and refactor infrastructure without affecting deployed resources.