Authenticating the CLI
terraform login # defaults to app.terraform.io
terraform login app.eu.terraform.io # or another hostname, such as a Terraform Enterprise instanceterraform loginopens a browser to create an API token and saves it to~/.terraform.d/credentials.tfrc.json.- In automation, use the environment variable
TF_TOKEN_app_terraform_io. Replace the dots in the hostname with underscores. terraform logoutremoves the saved token.
The cloud block
terraform {
cloud {
organization = "acme-corp"
workspaces {
name = "web-dev" # one specific workspace
}
}
}terraform {
cloud {
organization = "acme-corp"
workspaces {
tags = ["app:web"] # any workspace with this tag; switch with terraform workspace select
}
}
}Rules for the cloud block:
- It goes inside the
terraformblock. It replaces abackendblock, so you can't have both. hostnamedefaults toapp.terraform.io.- The
cloudblock is preferred over the legacybackend "remote". - Running
terraform initafter adding the block offers to migrate existing state into the workspace. It creates the workspace if it doesn't exist. - With
tags, theterraform workspacecommands list and select the matching HCP Terraform workspaces.terraform workspace newcreates a workspace carrying those tags. - Since 1.10,
tagscan also be a map of key-value tags. This course uses the list form (flagged). - Environment variables such as
TF_CLOUD_ORGANIZATION,TF_CLOUD_HOSTNAME, andTF_WORKSPACEcan supply settings, which allows a partially emptycloud {}block.
Three run workflows
| Workflow | How runs start | Notes |
|---|---|---|
| VCS-driven | The workspace is connected to a repo and branch. A push to the branch queues a plan. A pull request gets a speculative plan posted as a status check. | Apply happens after a manual "Confirm & Apply" in the UI, or automatically if auto-apply is on. You can't run terraform apply from the CLI against a VCS-connected workspace. |
| CLI-driven | terraform plan or apply on your machine uploads the configuration and streams the remote run's output to your terminal |
terraform plan from the CLI produces a speculative plan. Ctrl-C stops streaming, but the run continues remotely. |
| API-driven | A pipeline uploads a configuration version (a tarball) and creates runs through the API | Used for custom CI/CD integrations |
Execution modes (a workspace setting)
| Mode | Where Terraform runs | State |
|---|---|---|
| Remote (default) | On HCP Terraform-managed workers | HCP Terraform |
| Local | On your machine, as normal CLI | HCP Terraform, used only as a state backend |
| Agent | On self-hosted HCP Terraform agents inside your network (check your plan) | HCP Terraform |
With remote execution, the run can't see your laptop:
- Local environment variables aren't available.
- Credential files aren't available.
- Local services such as a Docker socket or an on-premises API aren't reachable.
Supply credentials as workspace variables (preferably dynamic provider credentials), or use agents for private networks.
The run pipeline
Pending → Plan → Cost estimation (if enabled) → Policy check → (Confirm) → Apply → AppliedRun tasks can hook in at the pre-plan, post-plan, pre-apply, and post-apply stages. Speculative plans stop after policy checks and can never be applied.