tfctl examples for HCP Terraform and Terraform Enterprise

This topic provides practical examples for common tfctl operations. Use these examples as starting points for your own workflows.

To reproduce the examples, set your active profile to the default organization. Refer to Manage tfctl profiles for setup instructions.

Advanced workflows

The following workflows combine tfctl commands to complete tasks that otherwise require several API calls, pagination handling, or UI pages.

Quickly diagnose a failed run

To investigate a run failure in HCP Terraform or Terraform Enterprise, you would normally open several pages in the UI. Instead, you can run a single tfctl command to find out why the latest run in a workspace.

The tfctl run status command accepts a workspace name, finds the latest run, and prints Terraform diagnostics, policy check failures, and run task failures together. Without tfctl, you look up the workspace ID, list its runs, and then query each part of the run.

Check the latest run in the workspace. Replace <WORKSPACE_NAME> with your workspace's name.
```
$ tfctl run status <WORKSPACE_NAME>
```
The command exits with code 6 if the run errored or a policy check failed, so you can also use it in scripts.

Get the latest run ID and summarize its plan:

$ RUN_ID=$(tfctl api /workspaces/{workspace}/runs \
    --pathparam workspace=<WORKSPACE_NAME> \
    --page-size 1 --jq '.data[0].id')
$ tfctl api /runs/{run}/plan --pathparam run="$RUN_ID" \
    --jq '.data.attributes | {
      status: .status,
      add: ."resource-additions",
      change: ."resource-changes",
      destroy: ."resource-destructions"
    }'

Preview and apply a bulk change across workspaces

Change a setting, such as the Terraform version, on every workspace that matches a name pattern.

tfctl fetches every page of matching workspaces in one command and previews each change with the global --dry-run flag before you send it. Without tfctl, you page through the workspaces API and send a PATCH request for each workspace.

Retrieve workspaces with names that end in -prod and save the workspace IDs to a file:

$ tfctl api /organizations/{organization}/workspaces \
    --field 'search[wildcard-name]=*-prod' --all \
    --jq '.data[].id' > workspaces.txt

Process the list of workspace IDs and use tfctl to preview the changes using the --dry-run flag. In the following example, <TERRAFORM_VERSION> specifies the Terraform version to set across workspaces, such as 1.9.8. tfctl prints each request without sending it.
```
$ while read -r ws; do
    tfctl api /workspaces/{workspace} --pathparam workspace="$ws" \
      --method PATCH --attribute terraform-version=<TERRAFORM_VERSION> \
      --dry-run
  done < workspaces.txt
```
Review the output, then run the same loop without --dry-run to apply the change.

Queue runs for the same workspaces. Use the same list to start a run in each workspace, for example after you publish a new module version. Preview the runs first, then remove --dry-run to queue them.

$ while read -r ws; do
    tfctl run start "$ws" --message "Module update rollout" --dry-run
  done < workspaces.txt

Compare organizations across instances

Check whether two organizations, such as an EU organization and a US organization on different HCP Terraform instances, contain the same workspaces.

The global --profile flag runs a single command against any configured profile, so you can query both instances without logging in again or switching profiles. This example uses the eu-org and us-org profiles from the Configure multiple profiles example.

$ tfctl get workspaces --all --profile eu-org \
    --jq '.data[].attributes.name' | sort > eu.txt
$ tfctl get workspaces --all --profile us-org \
    --jq '.data[].attributes.name' | sort > us.txt
$ diff eu.txt us.txt

The diff output lists workspaces that exist in only one organization.

Audit workspace settings with JSON output

Find workspaces whose settings do not match your standards.

The --all flag handles pagination and the global --jq flag filters the JSON response, so you do not need to write pagination logic or install a separate jq binary.

List workspaces that have auto-apply enabled:

$ tfctl get workspaces --all \
    --jq '.data[] | select(.attributes."auto-apply")
          | .attributes.name'

List workspaces that are not connected to a VCS repository:

$ tfctl get workspaces --all \
    --jq '.data[] | select(.attributes."vcs-repo" == null)
          | .attributes.name'

Export each workspace's name, Terraform version, and auto-apply setting to a CSV file:

$ tfctl get workspaces --all \
    --jq '.data[] | [.attributes.name,
          .attributes."terraform-version",
          .attributes."auto-apply"] | @csv' > workspaces.csv

Basic examples

The following examples show single operations.

Start a run and check its status

Start a new run using the tfctl run start command. Replace <WORKSPACE_NAME_OR_ID> with your workspace's name or ID.
```
$ tfctl run start <WORKSPACE_NAME_OR_ID> --message="Run started with tfctl."
```
The command creates a new run and displays the run ID.
Monitor the run status using the tfctl run status command. Replace <RUN_ID> with the run ID output from the previous command.
```
$ tfctl run status <RUN_ID>
```

Import workspace variables from a file

Create a Terraform variable definition file in HCL or JSON format with your variable definitions.
Import the variables using the tfctl variable import command:
```
$ tfctl variable import variables.hcl
```

Get workspace details by ID

Use the tfctl get command to get details about a workspace. Replace <WORKSPACE_ID> with your workspace's ID.

$ tfctl get <WORKSPACE_ID>

List all runs for a workspace

List all runs for a specific workspace. Replace <WORKSPACE_NAME_OR_ID> with your workspace's name or ID.

$ tfctl api /workspaces/{workspace}/runs \
    --pathparam workspace=<WORKSPACE_NAME_OR_ID>

Update workspace settings

Update workspace settings using a PATCH request. Replace <WORKSPACE_ID> with your workspace's ID.

$ tfctl api /workspaces/{workspace} \
  --method PATCH \
  --attribute auto-apply=true \
  --pathparam workspace=<WORKSPACE_ID>

Configure multiple profiles

Create a profile for each organization, then authenticate to each one. You must already have users with access to the organizations in each instance.

Create and configure a profile for each organization:

$ tfctl profile profiles create eu-org
$ tfctl profile set hostname app.eu.terraform.io --profile eu-org
$ tfctl profile set default_organization my-eu-org --profile eu-org
$ tfctl profile profiles create us-org
$ tfctl profile set hostname app.terraform.io --profile us-org
$ tfctl profile set default_organization my-us-org --profile us-org

Authenticate to each organization. The command opens your browser to generate an API token, then stores the token in the profile.
```
$ tfctl auth login --profile eu-org
$ tfctl auth login --profile us-org
```
Run commands against either organization with the --profile flag:
```
$ tfctl get workspaces --profile eu-org
$ tfctl get workspaces --profile us-org
```
To change the default profile, use the tfctl profile profiles activate command.