Terraform Workspaces and State Cheat Sheet

Manage Terraform CLI workspaces, local and remote state, imports, and state surgery commands.

View
StandardDetailedCompact
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all

Workspaces

Create, list, switch, and delete CLI workspaces.

List workspaces

Show available Terraform CLI workspaces for the current configuration.

bashANYterraformworkspacelist
bash
terraform workspace list
Notes

Show available Terraform CLI workspaces for the current configuration.

Show current workspace

Print the current Terraform CLI workspace name.

bashANYterraformworkspaceshow
bash
terraform workspace show
Notes

Print the current Terraform CLI workspace name.

Create workspace

Create and switch to a new workspace.

bashANYterraformworkspacenew
bash
terraform workspace new dev
Notes

Create and switch to a new workspace.

Select workspace

Switch to an existing workspace.

bashANYterraformworkspaceselect
bash
terraform workspace select prod
Notes

Switch to an existing workspace.

Delete workspace

Delete a Terraform CLI workspace.

bashANYterraformworkspacedelete
bash
terraform workspace delete dev
Notes

Delete a Terraform CLI workspace.

Import, Move, Remove

Bring existing infra under management and modify state safely.

Import existing object

Associate an existing infrastructure object with a resource address in state.

bashANYterraformimportstate
bash
terraform import aws_s3_bucket.logs my-logs-bucket
Notes

Associate an existing infrastructure object with a resource address in state.

Import with config generation

Generate configuration while importing supported resources.

bashANYterraformimportconfig-generation
bash
terraform import -generate-config-out=generated.tf aws_s3_bucket.logs my-logs-bucket
Notes

Generate configuration while importing supported resources.

Move state address

Rename or move a resource address in state.

bashANYterraformstatemv
bash
terraform state mv aws_instance.old aws_instance.new
Notes

Rename or move a resource address in state.

Remove resource from state

Stop tracking a resource without destroying the remote object.

bashANYterraformstaterm
bash
terraform state rm aws_instance.web
Notes

Stop tracking a resource without destroying the remote object.

Replace provider source in state

Update provider source addresses recorded in state.

bashANYterraformstatereplace-provider
bash
terraform state replace-provider hashicorp/aws registry.acme.corp/acme/aws
Notes

Update provider source addresses recorded in state.

State File Operations

Read and write raw state when needed.

Pull raw state JSON

Download the latest state and write it to a local file.

bashANYterraformstatepulljson
bash
terraform state pull > terraform.tfstate
Notes

Download the latest state and write it to a local file.

Push raw state JSON

Upload a local state file into the configured backend.

bashANYterraformstatepush
bash
terraform state push terraform.tfstate
Notes

Upload a local state file into the configured backend.

List module resources

List resources beneath a specific module path.

bashANYterraformstatelistmodule
bash
terraform state list module.network
Notes

List resources beneath a specific module path.

Providers and Backend Migration

Reconfigure backend and migrate state between backends.

Migrate state during init

Move state to a newly configured backend during re-init.

bashANYterraforminitmigrate-statebackend
bash
terraform init -migrate-state
Notes

Move state to a newly configured backend during re-init.

Force-copy backend state

Automatically copy existing state to a new backend without prompting.

bashANYterraforminitforce-copybackend
bash
terraform init -force-copy
Notes

Automatically copy existing state to a new backend without prompting.

Readonly provider lock file

Use providers from the dependency lock file without updating it.

bashANYterraforminitlockfile
bash
terraform init -lockfile=readonly
Notes

Use providers from the dependency lock file without updating it.

Remote State Patterns

Useful snippets for remote and local state workflows.

Plan with alternate state path

Use a non-default local state path for commands that support it.

bashANYterraformplanstatelocal-state
bash
terraform plan -state=terraform.tfstate
Notes

Use a non-default local state path for commands that support it.

Ignore files for remote runs

Exclude paths from uploaded configuration when using remote CLI-driven runs.

gitignoreANYterraformterraformignoreremote
gitignore
.terraformignore
.git/
.terraform/
node_modules/
*.pem
Notes

Exclude paths from uploaded configuration when using remote CLI-driven runs.

Remote backend snippet

Example backend configuration for HCP Terraform remote state and runs.

hclANYterraformbackendremotehcp
hcl
terraform {
  backend "remote" {
    organization = "acme"
    workspaces {
      name = "networking-prod"
    }
  }
}
Notes

Example backend configuration for HCP Terraform remote state and runs.