Pro ยท Lesson 7 of 12
A CLI workspace is a separate state name inside one backend. An HCP Terraform workspace is a remote run environment. They share a word and not a meaning.
Sign in to save your place.
CLI workspaces are extra notebooks in the same desk, all using the same shopping list. An HCP workspace is a different desk, with its own notebook, its own keys, and its own clerk. Calling both a workspace is how people apply the wrong notebook.
terraform workspace new dev creates a named state. terraform workspace select dev points the next plan at it. The configuration is the same. terraform.workspace returns the name so a config can branch. The default name is default.
This is a weak way to separate production from development. One directory, one set of files, and a selected name. The mistake is selecting the wrong name and applying. Many teams use separate directories or separate backend keys instead, so production is a different folder you have to mean to enter.
In HCP Terraform, a workspace is the remote object that holds variables, state, a run history, and permissions. It is not the CLI command terraform workspace. You can connect a CLI to one HCP workspace. Creating a second CLI workspace inside that remote setup is a different feature and easy to confuse.
OpenTofu does not gain HCP workspaces by using similar CLI flags. HCP Terraform runs HashiCorp's product. If a team standardizes on tofu, they need a runner that executes that binary. Pointing an HCP workspace at the code does not switch the binary for you.
| Word | What it is | What it is not |
|---|---|---|
| terraform workspace | A state namespace in the backend | A separate permission boundary |
| HCP Terraform workspace | A remote run, with variables and state | The OpenTofu control plane |
| A second directory | A separate root module | Automatically a different cloud account |
Step 1 of 3One configuration, several state names. You select one.
Step 2 of 3An HCP workspace is a remote environment with its own settings.
Step 3 of 3Separate root modules make the production apply a deliberate directory change.
From a lab directory that already ran terraform init. Do not select a workspace you do not understand in a directory that has real cloud resources.
terraform workspace list
# default is the one you already have
# terraform workspace new lab-only
# terraform workspace select default
Checked against the linked documentation in October 2026. A later release can move a flag, a price, or a supported pair. Use the page for the version you installed.