HCP Terraform CLI (hcptf)

Use the CLI with workspace/run hierarchical commands and URL-style navigation.

When to Use This Skill

Use this skill when:

• Managing HCP Terraform workspaces, runs, or organizations

• Working with Terraform Stacks or private registry resources

• Automating infrastructure deployments

• Querying resource state across organizations

• User mentions "Terraform Cloud", "HCP Terraform", or "TFE"

Authentication

The CLI checks for credentials in this order:

• TFE_TOKEN environment variable

• HCPTF_TOKEN environment variable

• ~/.hcptfrc configuration file

• ~/.terraform.d/credentials.tfrc.json (shared with Terraform CLI)

Quick Setup

Interactive login (recommended)

hcptf login

Or set environment variable

export TFE_TOKEN="your-token-here"

Command Structure

The CLI uses a hierarchical namespace structure for organization:

Hierarchical Commands

Registry commands

hcptf registry # Show all registry commands hcptf registry module list -org=my-org hcptf registry provider create -org=my-org -name=custom hcptf registry provider version create -org=my-org -name=aws -version=3.1.1 -key-id=GPG_KEY

Stack commands

hcptf stack # Show all stack commands hcptf stack list -org=my-org -project=prj-123 hcptf stack configuration list -stack-id=stk-123 hcptf stack deployment create -stack-id=stk-123 hcptf stack state list -stack-id=stk-123

Explorer API (query across org)

hcptf explorer query -org=my-org -type=providers -sort=-version

Traditional Commands

Workspace operations

hcptf workspace list -org=my-org hcptf workspace create -org=my-org -name=staging hcptf workspace read -org=my-org -name=staging

Run operations

hcptf workspace run list -org=my-org -name=staging hcptf workspace run create -org=my-org -name=staging -message="Deploy" hcptf workspace run show -id=run-abc123 hcptf workspace run apply -id=run-abc123 hcptf workspace run cancel -id=run-abc123 hcptf workspace run discard -id=run-abc123 hcptf workspace run assessmentresult list -org=my-org -name=staging hcptf workspace run assessmentresult read -id=asmtres-abc123 -show-drift

Variables

hcptf variable create -org=my-org -workspace=staging -key=region -value=us-east-1 hcptf variable create -org=my-org -workspace=staging
-key=AWS_SECRET -value=secret -category=env -sensitive

URL-Style Navigation

For interactive exploration, use path-like syntax:

Organization level

hcptf my-org # Show org details hcptf my-org workspaces # List workspaces hcptf my-org projects # List projects hcptf my-org teams # List teams

Workspace level

hcptf my-org my-workspace # Show workspace details hcptf my-org my-workspace runs # List runs hcptf my-org my-workspace assessments # List assessment results hcptf my-org my-workspace variables hcptf my-org my-workspace state

Run operations

hcptf my-org my-workspace runs run-abc123 # Show run hcptf my-org my-workspace runs run-abc123 apply # Apply run

Common Workflows

Create Workspace and Deploy

Create workspace

hcptf workspace create -org=my-org -name=production
-auto-apply=false
-terraform-version=1.6.0

Set variables

hcptf variable create -org=my-org -workspace=production
-key=environment -value=prod

Trigger run

hcptf workspace run create -org=my-org -name=production
-message="Initial deployment"

Check status

hcptf workspace run show -id=run-abc123

Apply when ready

hcptf workspace run apply -id=run-abc123 -comment="Approved by team"

Manage Private Registry

List modules

hcptf registry module list -org=my-org

Create provider

hcptf registry provider create -org=my-org
-name=custom-aws
-namespace=my-org

Add provider version

hcptf registry provider version create -org=my-org
-name=custom-aws
-version=1.0.0
-key-id=ABC123

Add platform binary

hcptf registry provider platform create -org=my-org
-name=custom-aws
-version=1.0.0
-os=linux
-arch=amd64
-filename=terraform-provider-custom-aws_1.0.0_linux_amd64.zip

Work with Stacks

List stacks

hcptf stack list -org=my-org -project=prj-abc123

Create stack

hcptf stack create -org=my-org
-project=prj-abc123
-name=production-stack

List configurations

hcptf stack configuration list -stack-id=stk-abc123

Trigger deployment

hcptf stack deployment create -stack-id=stk-abc123

Check deployment status

hcptf stack deployment read -deployment-id=dep-abc123

View state

hcptf stack state list -stack-id=stk-abc123

Query Resources with Explorer

Find providers across organization

hcptf explorer query -org=my-org
-type=providers
-sort=-version

Query workspaces

hcptf explorer query -org=my-org
-type=workspaces
-filter="name:production"

Export to CSV

hcptf explorer query -org=my-org
-type=tf_versions
-export-csv
-output=versions.csv

Agent-Friendly Features

The CLI is designed to work well when driven by AI agents. Always use these features when automating with hcptf.

Schema Introspection

Before constructing commands, discover available flags as structured JSON:

Get machine-readable flag schema for any command

hcptf schema workspace create hcptf schema variable create hcptf schema run apply

Returns JSON with flag names, types, required status, aliases, and defaults. Always use hcptf schema instead of parsing --help text.

Dry Run (validate without executing)

Always use -dry-run before mutations to validate inputs without making API calls:

Preview what would happen

hcptf workspace delete -org=my-org -name=staging -dry-run hcptf variable create -org=my-org -workspace=prod -key=region -value=us-east-1 -dry-run hcptf run apply -id=run-abc123 -dry-run

Returns JSON describing the planned action. No API call is made.

JSON Input for Mutations

Pass full API payloads instead of individual flags using -json-input :

Inline JSON

hcptf variable create -org=my-org -workspace=prod
-json-input='{"key":"region","value":"us-east-1","category":"terraform"}'

From file

hcptf workspace create -org=my-org -json-input=@workspace.json

From stdin

cat config.json | hcptf workspace create -org=my-org -json-input=-

Note: Routing flags like -org and -workspace are still required alongside -json-input .

Field Filtering

Limit output to specific fields with -fields to reduce response size:

Only return ID and Name

hcptf workspace list -org=my-org -fields=Name,ID -output=json hcptf workspace read -org=my-org -name=prod -fields=ID,Name,Status hcptf variable create -org=my-org -workspace=prod -key=x -value=y -fields=ID,Key

Input Validation

All mutation commands validate inputs against common agent mistakes:

• Path traversal (../ ) is rejected

• Query injection (? , & ) is rejected

• URL-encoded sequences (%2f ) are rejected

• Control characters are rejected

• Overly long strings are rejected

Recommended Agent Workflow

1. Discover flags for the command

hcptf schema workspace create

2. Dry-run to validate

hcptf workspace create -org=my-org -name=staging -dry-run

3. Execute with JSON output and field filtering

hcptf workspace create -org=my-org -name=staging -output=json -fields=ID,Name

4. For complex mutations, use JSON input

hcptf workspace create -org=my-org
-json-input='{"name":"staging","terraform-version":"1.6.0","auto-apply":false}'
-output=json -fields=ID,Name

Output Formats

Table Output (Default)

hcptf workspace list -org=my-org

JSON Output (for scripting and agents)

hcptf workspace list -org=my-org -output=json

Filtered JSON Output

hcptf workspace list -org=my-org -output=json -fields=Name,ID,Status

Best Practices

Always use -dry-run before write/delete commands to confirm the action is correct before executing

Always confirm with user before write/delete commands — never auto-execute mutations without user approval

Use hcptf schema to discover flags — never guess flag names or parse help text

Use -output=json and -fields for automation — reduces output size and gives structured data

Use hierarchical commands for clarity

• hcptf workspace run create for run workflows

• hcptf workspace run assessmentresult list for drift workflows

Prefer explicit flags for automation

• Use -org= and -name= in scripts

• -workspace= remains available as alias

• URL-style is great for interactive use

Check status before applying

Always review before apply

hcptf workspace run show -id=run-abc123 hcptf workspace run apply -id=run-abc123

Sensitive variables

Always use -sensitive for secrets

hcptf variable create -org=my-org -workspace=prod
-key=API_KEY -value=secret -sensitive

Check drift before deployment

Assessment results show drift

hcptf workspace run assessmentresult list -org=my-org -name=prod hcptf workspace run assessmentresult read -id=ar-abc123 -show-drift hcptf workspace run create -org=my-org -name=prod -refresh-only

Common Flags

Flag Alias Description

-organization

-org

Organization name

-name

-workspace

Workspace name

-output

table (default) or json

-force

Skip confirmation prompts

-dry-run

Validate without making API calls

-fields

Comma-separated output field filter

-json-input

JSON payload (inline, @file , - )

Getting Help

General help

hcptf --help

Command group help

hcptf registry --help hcptf stack --help

Specific command help

hcptf workspace create --help hcptf registry module list --help

Error Handling

When commands fail:

• Check authentication: Ensure TFE_TOKEN is set or run hcptf login

• Verify organization: Confirm you have access to the org

• Check resource names: Workspaces and runs must exist

• Review permissions: Ensure your token has required permissions

Examples

Complete Workspace Setup

Create workspace with VCS

hcptf workspace create -org=my-org -name=api-service
-vcs-repo=owner/repo
-vcs-branch=main
-working-directory=terraform/

Configure variables

hcptf variable create -org=my-org -workspace=api-service
-key=environment -value=staging

hcptf variable create -org=my-org -workspace=api-service
-key=AWS_ACCESS_KEY_ID -value=$AWS_KEY -category=env -sensitive

Set up notifications

hcptf notification create -org=my-org -workspace=api-service
-name=slack-alerts
-destination-type=slack
-url=$SLACK_WEBHOOK
-triggers=run:completed,run:errored

State Management

List state versions

hcptf state list -org=my-org -workspace=production

View state outputs

hcptf state outputs -org=my-org -workspace=production

Export state

hcptf state read -org=my-org -workspace=production -output=json > state.json

Policy Management

Create policy

hcptf policy create -org=my-org
-name=cost-limit
-enforce-mode=hard-mandatory
-policy-file=policies/cost.sentinel

Create policy set

hcptf policyset create -org=my-org
-name=production-policies
-global=true

Add policy to set

hcptf policyset add-policy -org=my-org
-policyset=production-policies
-policy=cost-limit

Troubleshooting

Authentication Issues

Verify token is valid

hcptf account show

Re-login if needed

hcptf logout hcptf login

Finding Resource IDs

Get workspace ID

hcptf workspace read -org=my-org -workspace=staging -output=json |
jq -r '.data.id'

Get latest run ID

hcptf workspace run list -org=my-org -name=staging -output=json |
jq -r '.data[0].id'

Debugging

Use JSON output for detailed info

hcptf workspace run show -id=run-abc123 -output=json | jq .

Check drift in assessment results

hcptf workspace run assessmentresult read -id=ar-abc123 -show-drift -summary-only

Reference

• Authentication: See hcptf login --help

• Configuration: ~/.hcptfrc (HCL format)

• Documentation: README.md in repository

• API Coverage: 100+ commands across 50+ resource types

Notes

• All commands support -help flag for detailed usage

• Hierarchical structure (registry, stack) is the current standard

• Legacy flat commands have been removed in favor of hierarchical

• URL-style navigation works alongside traditional commands