go-tfstate

A CLI tool for viewing and manipulating Terraform state files. It allows you to inspect, search, update, and remove resources from your Terraform state without needing to use Terraform commands directly.

Why This Tool Exists

Terraform state files are the single source of truth for your infrastructure's current state. In ideal scenarios, you should never need to manually edit these files - Terraform manages them automatically through its lifecycle commands (terraform plan, terraform apply, etc.).

However, there are situations where direct state manipulation becomes necessary:

• Orphaned Resources: Resources that exist in the state but have been manually deleted from the cloud provider
• Provider Changes: Migrating between provider versions or configurations
• State Corruption: Fixing inconsistencies caused by interrupted operations or manual interventions
• Refactoring: Cleaning up after major infrastructure changes or module reorganizations

⚠️ Important Warning

You should NOT edit Terraform state files unless absolutely necessary. Direct state manipulation can lead to:

• Data Loss: Inconsistent state between Terraform and actual infrastructure
• Security Issues: Accidental exposure of sensitive data in state files
• Operational Problems: Terraform losing track of resource dependencies and relationships
• Team Conflicts: State file changes not reflected in version control or team workflows

Always prefer Terraform's built-in commands first:

• Use terraform state rm to remove resources
• Use terraform state mv to rename/move resources
• Use terraform import to bring existing resources under management
• Use terraform refresh to update state from actual infrastructure

Only use this tool when Terraform's commands cannot resolve your situation, and always:

• Create backups before making changes
• Use dry-run mode (--dry-run) to preview changes
• Test changes in a safe environment first
• Communicate with your team about state modifications

Features

• List Resources: Display all resources in a Terraform state file with their indices, types, names, and modes.
• Search Resources: Find resources by type, name, module, provider, or attribute values using flexible search patterns.
• Update Attributes: Modify specific attributes of resource instances (with protection for sensitive instance resources).
• Remove Resources: Delete resources from the state file by index (with protection for instance resources).
• Update Providers: Change provider strings globally by substring replacement or for specific resource indices.
• Dry Run Mode: Preview changes without writing to disk.
• In-Place Editing: Modify the state file directly or save to a new file.
• Force Mode: Override protections for instance resources (use with caution).
• Protected Resources: Automatic protection for instance-type resources to prevent accidental modifications.

Example Usage

Search for resources

./bin/go-tfstate -f example_state/terraform-statefile -list
0: google_sql_database_instance.test_cloudsql_mysql (managed)
1: google_sql_user.root_user (managed)
2: google_sql_user.app_user (managed)


./bin/go-tfstate -f example_state/terraform-statefile -s root
1: google_sql_user.root_user (managed) [module: , provider: provider["registry.terraform.io/hashicorp/google"]]

Suggested remove command: ./bin/go-tfstate -f example_state/terraform-statefile -remove 1 -o <output_file>

This will list all matching resources and suggest a remove command with the indices.

Build

make build

Binaries will be placed in the bin/ directory:

• bin/go-tfstate-darwin-amd64
• bin/go-tfstate-linux-amd64

Clean build artifacts:

make clean

Testing

Run all tests with verbose output to see which tests are executing:

go test -v ./pkg/tfstate/

Or use the Makefile targets:

make test-verbose    # Run tests with verbose output
make test-cover      # Run tests with coverage report
make test-all        # Run all tests in the project

Run a specific test:

go test -v ./pkg/tfstate/ -run TestUpdateProvidersBySubstring

Run tests with coverage report:

go test -v -cover ./pkg/tfstate/

Run all tests in the project:

go test -v ./...