Plain language
CLI workspaces let one configuration and one backend hold multiple named states.
terraform workspace list # * marks the current one
terraform workspace show
terraform workspace new staging # create and switch
terraform workspace select default
terraform workspace select -or-create dev
terraform workspace delete staging # must be empty unless -force- Every backend starts with a
defaultworkspace, which can't be deleted. - Inside configuration,
terraform.workspacereturns the current name:name = "web-${terraform.workspace}". - The
TF_WORKSPACEenvironment variable selects a workspace without runningselect.
Under the hood
| Backend | Where workspace state lives |
|---|---|
| Local | terraform.tfstate.d/<name>/terraform.tfstate |
| S3 | Under an env:/<name>/ prefix, configurable with workspace_key_prefix |
| Others | Equivalent separate keys, if the backend supports multiple workspaces |
When to use CLI workspaces
HashiCorp's guidance: CLI workspaces suit temporary or parallel copies of the same infrastructure, such as testing a feature branch. They aren't suitable when environments need separate credentials or access controls, because every workspace shares the same backend and configuration. For strongly isolated environments like prod and dev, use separate configurations or backends, or HCP Terraform workspaces.
CLI workspaces vs. HCP Terraform workspaces
| CLI workspace | HCP Terraform workspace | |
|---|---|---|
| What it is | Another named state in the same backend | A full unit of work: state, variables, run history, VCS settings, permissions, policies |
| Separate variables | No. Same config and tfvars. | Yes, per workspace |
| Separate access control | No | Yes, team permissions per workspace or project |
| Run history and audit | No | Yes |
Module 8 covers HCP Terraform workspaces in detail.