Although the names are the same, CLI workspaces and HCP Terraform workspaces are different concepts. Keep this distinction in mind when designing your workflow and organizing environments.
CLI workspaces vs HCP Terraform workspaces
CLI workspaces and HCP Terraform workspaces both help manage multiple infrastructure environments, but they solve different problems and operate at different scopes.| Aspect | CLI Workspaces | HCP Terraform Workspaces |
|---|---|---|
| Scope | Local directory-level state isolation | Full remote environment with config, state, runs, variables, and access controls |
| State | Multiple state files in the working directory | Single encrypted state per workspace with version history and rollback |
| Management | Managed locally with the Terraform CLI (terraform workspace new, terraform workspace select) | Managed via HCP UI, CLI, or API; supports teams and production workflows |
| Use case | Lightweight environment switching for local testing | Team-oriented lifecycle, auditability, and access control for production and CI/CD |
What an HCP Terraform workspace contains
- Terraform configuration
.tffiles are provided to the workspace by linking a VCS repository (GitHub, GitLab, Bitbucket, etc.) or by uploading/running from the CLI against the workspace.
- State file and history
- Remote, encrypted state with full version history and rollback capability.
- Variables
- Plaintext and sensitive variables can be stored in the workspace; sensitive values are write-only.
- Run history
- Every plan, apply, and destroy is recorded with user identity, timestamps, change details, and logs.
- Execution settings
- Execution mode, pinned Terraform version, and
auto-applysettings per workspace.
- Execution mode, pinned Terraform version, and
- Team access and permissions
- Fine-grained controls over who can view, plan, apply, or modify workspace settings.
How workspaces fit into the organization structure
Workspaces belong to an HCP Terraform organization (the top-level container). An organization can contain many workspaces; each workspace is insulated with its own configuration, state, variables, and run history. Changes in one workspace do not affect another. Example naming pattern for clarity and reduced blast radius:networking-prod,networking-devapp1-prod,app1-devmonitoring-prod,monitoring-dev
Inside a single workspace
In a single workspace you will typically manage:- Variables: Environment-specific inputs (region, instance types, credentials).
- Terraform version: Pin a workspace to a Terraform version (e.g.,
1.5) to ensure consistent remote runs. - Run history and audits: Detailed logs for plans and applies for traceability and debugging.
- Permissions: Workspace-level IAM to control who can plan/apply or manage variables.
- State file: Encrypted-at-rest and versioned per workspace.
- Terraform configuration:
.tffiles linked via VCS or uploaded from the CLI.
HCP Terraform encrypts workspace state at rest automatically — you do not need to configure separate encryption for workspace state.
VCS connections and the VCS-driven workflow
Linking a workspace to a version control system (VCS) repository enables a declarative, reviewable workflow where infrastructure changes are tied to code changes. Typical VCS-driven flow:- Developer updates code locally and pushes a commit or opens a pull request.
- HCP Terraform detects the change and creates a plan in the linked workspace.
- The team reviews the plan and either approves/apply manually or relies on
auto-applyto apply automatically after a successful plan.
Workspace workflows — how runs are triggered
When creating a workspace you select a workflow type; this determines how runs are initiated and how state changes propagate.| Workflow Type | Trigger | Best for | Example |
|---|---|---|---|
| Version Control Workflow | Commits / Pull Requests | Teams that want traceability and reviewable plans | Link workspace to GitHub repo to auto-create plans on PRs |
| CLI-Driven Workflow | Local CLI (after terraform login) | Individuals or teams who prefer direct CLI control with remote execution | terraform plan / terraform apply against the HCP backend |
| API-Driven Workflow | HCP Terraform API calls | Custom automation, CI/CD pipelines, or integrations | GitHub Actions calling HCP API to trigger runs |
Best practices
- Use one workspace per logical component/environment to reduce blast radius.
- Pin Terraform versions per workspace to avoid drift between local and remote runs.
- Prefer VCS-driven workflows for team environments to enforce code review and traceability.
- Mark sensitive variables as sensitive in the workspace to prevent accidental disclosure.
- Use workspace-level permissions to separate duties (e.g., reviewers vs operators).
Summary
- CLI workspaces and HCP Terraform workspaces are distinct: CLI workspaces are for local state isolation, while HCP Terraform workspaces are full remote environments for team use.
- An HCP Terraform workspace includes configuration, encrypted state with history, variables (including sensitive values), run history, execution settings, and access controls.
- Workspaces live under an organization and are typically used one-per logical component/environment to limit blast radius.
- Choose a workspace workflow that aligns with your team’s needs: VCS-driven for traceability, CLI-driven for direct control, or API-driven for automation.