Skip to content

Terrafrom CLI and Workspaces

Terraform Workspaces

Terraform Workspaces (not to be confused with Terraform Cloud Workspaces) allow you to manage multiple environments or maintain alternate state files (e.g., dev, prod) within the same configuration. In early versions of Terraform, they were referred to as environments.

By default, the local backend starts with a single workspace called default, which is special and cannot be deleted.

Workspace Internals

When using the local backend, Terraform stores workspace-specific state files inside the terraform.tfstate.d/ directory. Each workspace gets its own subfolder.

When using a remote backend, workspace state files are stored directly in the configured backend instead. This is the recommended approach for production environments.

You can reference the current workspace name using the built-in variable terraform.workspace:

resource "aws_instance" "example" {
    tags = {
        Name = "web-${terraform.workspace}"
    }
}

Terraform CLI commands

terraform init

Initializes a Terraform project:

  • Downloads plugin dependencies (Providers & Modules)
  • Creates .terraform directory
  • Creates .terraform.lock.hcl to lock terraform and plugin versions

This is generally the first command you will run for a new terraform project. If you modify or change dependencies run terraform init again to have it apply the changes.

Flags:

  • -upgrade → upgrade all plugins to the latest version within version constraints
  • -get-plugins=false → skip plugin installation
  • -plugin-dir=PATH → force plugin installation from a local directory
  • -lockfile=MODE → configure lockfile behavior

Notes: .terraform.tfstate.lock.hcl — used for state file locking

terraform get

Downloads and updates modules in the root module without initializing state or providers.

terraform fmt

Formats .tf files according to style conventions for readability.

  • terraform fmt --diff shows what would change

terraform validate

Validates syntax and internal consistency without using variables or state.

  • Automatically run during plan or apply

terraform console

Interactive shell for evaluating expressions and debugging

terraform plan

Generates an execution plan:

  • Reads current state from the backend
  • Refreshes the state by reading the actual resources
  • Compares the current configuration to the existing state
  • Proposes changes (add, update, delete)

Two categories:

  • Speculative plans → manually running terraform apply outputs a plan and prompts for "yes"
  • Saved plans → terraform plan -out=FILE → a saved planfile is being generated that can be passed along to terraform apply FILE for unattended apply

Notes:

  • terraform plan doesn't carry out proposed changes
  • a terraform plan file is a binary file.

terraform apply

Executes the proposed changes from a plan:

  • Can operate from speculative plan or saved plan
  • Manual approval required if speculative

terraform workspace CLI commands

  • terraform workspace list - list all existing workspaces
  • terraform workspace show - display the current workspace
  • terraform workspace select <WORKSPACE> - switch to an existing workspace
  • terraform workspace new <WORKSPACE> - create and switch to a new workspace
  • terraform workspace delete <WORKSPACE> - delete a workspace