hcpctl

A CLI for HCP Terraform (formerly Terraform Cloud/Enterprise)

hcpctl get ws                    # List all workspaces
hcpctl get ws my-workspace       # Get specific workspace
hcpctl get prj -o yaml           # List projects as YAML
hcpctl get org                   # List organizations

Features

Command	Resources	Capabilities
`get`	`oc`	List/filter OAuth clients (VCS connections)
	`org-member`	List/filter organization members by email/status
	`org`	List/filter organizations
	`prj`	List/filter/sort projects, show workspace counts/names/IDs
	`run`	List active runs (non-final states), filter by status/workspace, fetch subresources (events, plan, apply), stream/download logs
	`team`	List/filter teams in organization
	`ws`	List/filter/sort workspaces, group by org/project, fetch subresources (current-run, current-state-version, current-configuration-version, current-assessment-result)
`logs`	—	View plan/apply logs for run or workspace's current run, follow in real-time
`watch`	`ws`	Continuously monitor workspace for new runs, auto-stream logs
`invite`	—	Invite user to organization, optionally assign to teams
`delete`	`org-member`	Remove user from organization (by ID or email)
`purge`	`run`	Cancel/discard pending runs blocking a workspace
	`state`	Zero out all resources from workspace state (with mandatory confirmation)
`update`	—	Self-update to latest version

Output formats: table (default), json, yaml, csv

Global options: --host, --token, --batch (no prompts/spinners), --no-header

Documentation

For complete command reference, see Command Line Help.

hcpctl --help           # General help
hcpctl get --help       # Get command help
hcpctl get ws --help    # Workspace-specific options

Installation

Linux / macOS

curl -fsSL \
  https://raw.githubusercontent.com/pkodzis/hcpctl/main/scripts/install.sh | bash

Or with custom install directory:

INSTALL_DIR=/usr/local/bin \
  curl -fsSL \
  https://raw.githubusercontent.com/pkodzis/hcpctl/main/scripts/install.sh | bash

Windows (PowerShell)

Invoke-RestMethod `
  https://raw.githubusercontent.com/pkodzis/hcpctl/main/scripts/install.ps1 `
  | Invoke-Expression

From Source

Requires Rust:

git clone https://github.com/pkodzis/hcpctl.git
cd hcpctl
cargo install --path .

Configuration

Set your HCP Terraform token:

export TFE_TOKEN="your-token-here"

Optionally set default host and organization:

export TFE_HOST="app.terraform.io"
export TFE_ORG="my-organization"

Or use Terraform CLI credentials file (~/.terraform.d/credentials.tfrc.json).

Run hcpctl get --help for full credential resolution details.

Development Environment

Prerequisites

Linux / macOS (Development)

# Install Rust toolchain
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

# Verify installation
rustc --version
cargo --version

# Install development tools
cargo install cross        # Cross-compilation support
cargo install cargo-edit   # Adds `cargo add`, `cargo upgrade` commands
cargo add clap-markdown    # for building CLI command reference
cargo install mdbook       # for building html doc

Windows

# Install Rust toolchain from https://rustup.rs
# Download and run rustup-init.exe

# Verify installation (in new terminal)
rustc --version
cargo --version

# Install development tools
cargo install cross
cargo install cargo-edit

Build & Test

# Clone the repository
git clone https://github.com/pkodzis/hcpctl.git
cd hcpctl

# Install pre-commit hooks
pip install pre-commit
pre-commit install
pre-commit install --hook-type pre-push

# Build
cargo build

# Run tests
cargo test

Getting Started with hcpctl

hcpctl is a command-line interface for HCP Terraform (formerly Terraform Cloud) and Terraform Enterprise, designed to feel familiar to users of kubectl.

Installation

You can install hcpctl using the provided installation scripts:

Linux / macOS:

curl -sSL https://hcpctl.com/install.sh | bash

Windows (PowerShell):

irm https://hcpctl.com/install.ps1 | iex

First Steps

Before you can use hcpctl, you need to authenticate with HCP Terraform.

The recommended way is to use the standard Terraform CLI authentication. If you have terraform installed, simply run:

terraform login

This will open your browser, generate an API token, and save it to ~/.terraform.d/credentials.tfrc.json. hcpctl will automatically read this file and use the token.

Alternatively, you can set the HCP_TOKEN environment variable directly:

export HCP_TOKEN="your-terraform-cloud-token"

You can also use TFC_TOKEN or TFE_TOKEN.

Tip: You can generate a token manually in the HCP Terraform UI under User Settings -> Tokens.

Basic Usage

The core command pattern is hcpctl <verb> <resource> [name] [flags].

Listing Resources

To list all organizations you have access to:

hcpctl get org

To list workspaces in a specific organization:

hcpctl get ws --org my-organization

Getting Specific Resources

To get details about a specific workspace:

hcpctl get ws my-workspace --org my-organization

Output Formats

Like kubectl, you can change the output format using the -o or --output flag. Supported formats are table (default), json, yaml, and csv.

hcpctl get ws my-workspace --org my-organization -o yaml

Next Steps

Learn more about Authentication and Contexts to manage multiple environments.
Use Contexts and Multi-Environment Workflows for production/dev setup patterns.
Explore Workspace Management to see how to organize your infrastructure.
See Runs and Logs to learn how to monitor Terraform executions.

Authentication and Contexts

hcpctl needs to know which HCP Terraform / Terraform Enterprise host to connect to, and what API token to use. It supports multiple ways to provide these credentials.

Resolution Order

When you run a command, hcpctl resolves the Host and Token in the following order (first match wins):

Host Resolution

CLI argument (-H or --host)
Environment variable (TFE_HOSTNAME)
Active Context
Terraform Credentials file (~/.terraform.d/credentials.tfrc.json)

Token Resolution

CLI argument (-t or --token)
Environment variables (HCP_TOKEN, TFC_TOKEN, TFE_TOKEN)
Active Context
Terraform Credentials file (~/.terraform.d/credentials.tfrc.json)

Using Contexts

If you work with multiple organizations or multiple Terraform Enterprise instances, Contexts are the best way to manage your configuration. They work exactly like kubectl contexts.

Creating a Context

You can create a context that stores your host, token, and default organization:

hcpctl config set-context prod \
  --host app.terraform.io \
  --token $HCP_TOKEN \
  --org my-production-org

Switching Contexts

To use a context, set it as the current context:

hcpctl config use-context prod

Now, any command you run will automatically use the host, token, and organization from the prod context. You no longer need to pass --org my-production-org to every command!

Managing Contexts

List all configured contexts:

hcpctl config get-contexts

Show the currently active context:

hcpctl config current-context

Delete a context:

hcpctl config delete-context prod

Show full raw config:

hcpctl config view

Select context for a single command:

hcpctl --context prod get ws

You can also set context via environment variable:

export HCPCTL_CONTEXT=prod

Active context name resolution order is:

--context
HCPCTL_CONTEXT
current-context in hcpctl config file

Terraform Credentials File

If you already use the standard terraform CLI, you likely have a credentials file at ~/.terraform.d/credentials.tfrc.json (or %APPDATA%\terraform.d\credentials.tfrc.json on Windows).

hcpctl automatically reads this file. If you only have one host configured in it, hcpctl will use it automatically. If you have multiple hosts, hcpctl will prompt you to select one interactively.

In --batch mode, interactive host selection is disabled. If multiple hosts exist and none was explicitly provided (--host, TFE_HOSTNAME, context), command fails with an error.

Contexts and Multi-Environment Workflows

If you work with multiple HCP Terraform or Terraform Enterprise environments (for example: dev, stage, prod), contexts are the safest way to avoid using the wrong host/org/token.

Why and when to use

Use contexts when you:

switch between multiple hosts,
use different default organizations,
want shorter commands without repeating --host, --token, --org.

Common tasks

1. Create contexts

hcpctl config set-context dev --host app.terraform.io --org my-dev-org
hcpctl config set-context prod --host tfe.company.internal --org my-prod-org

You can include token directly:

hcpctl config set-context prod --token "$TFE_TOKEN"

2. Switch active context

hcpctl config use-context dev
hcpctl config current-context

3. List configured contexts

hcpctl config get-contexts

4. Use one-off context override

hcpctl --context prod get ws

Advanced variants

Environment-driven context selection

export HCPCTL_CONTEXT=prod
hcpctl get run --org my-prod-org

Active context name is resolved in this order:

--context
HCPCTL_CONTEXT
current-context in config

Safe defaults + explicit overrides

Keep default org in context, but override for one command:

hcpctl --context prod get ws --org emergency-org

Pitfalls and troubleshooting

"Why did command use wrong host?"

Host resolution order is:

--host
TFE_HOSTNAME
active context host
Terraform credentials file

If behavior is unexpected, check env vars first:

env | grep -E 'HCPCTL_CONTEXT|TFE_HOSTNAME|HCP_TOKEN|TFC_TOKEN|TFE_TOKEN'

Multiple hosts in credentials file + batch mode

In normal mode, hcpctl may ask you to choose host interactively.

In --batch mode, no prompt is shown. If multiple hosts are available and host is not explicitly set, command fails.

Context missing after deletion

If you delete the current context, current-context becomes empty. Set a new one:

hcpctl config use-context dev

Managing Workspaces and Projects

Workspaces are the core resource in HCP Terraform. hcpctl provides powerful tools to list, filter, and modify workspaces and their associated projects.

Listing and Filtering Workspaces

You can list all workspaces in an organization:

hcpctl get ws --org my-org

Filtering

Use the -f or --filter flag to search for workspaces by name. This performs a partial match:

hcpctl get ws -f "network" --org my-org

Sorting

You can sort the output using the -s or --sort flag. For workspaces, available sort fields are:

name
resources
updated-at
tf-version
pending-runs (requires --has-pending-runs)

Use -r to reverse the sort order.

hcpctl get ws --sort updated-at -r --org my-org

To focus only on workspaces blocked by queued runs:

hcpctl get ws --org my-org --has-pending-runs --sort pending-runs -r

Workspace Subresources

You can fetch specific subresources of a workspace using the --subresource flag. This is useful for getting the current state version, current run, or configuration version.

Supported values are:

run
state
config
assessment

--subresource works only with a single workspace (hcpctl get ws <NAME_OR_ID>) and JSON/YAML output.

hcpctl get ws my-workspace --org my-org --subresource state -o yaml

Downloading Configuration

If you need to inspect the actual Terraform code that is currently loaded into a workspace (the Configuration Version), you can download it directly:

hcpctl download config my-workspace --org my-org

This will download the .tar.gz archive containing the Terraform configuration files that were uploaded for the current run.

Modifying Workspaces

The set command allows you to modify workspace properties.

Moving a Workspace to a Project

To move a workspace to a different project:

hcpctl set ws my-workspace --prj "Core Infrastructure" --org my-org

You can also update Terraform version in the same command:

hcpctl set ws my-workspace --terraform-version 1.12.2 --org my-org

Managing Tags

Tags in HCP Terraform are managed as separate bindings. You can get, set, and delete tags on workspaces and projects.

Viewing Tags

hcpctl get tag ws my-workspace --org my-org

Adding Tags

You can add multiple tags at once. Tags are positional arguments (space-separated), not a --tags flag.

Workspaces support mixed tag types:

flat tags: env
key-value bindings: team=platform

hcpctl set tag ws my-workspace env team=platform --org my-org

Removing Tags

hcpctl delete tag ws my-workspace env team --org my-org

For projects, only key=value tags are supported:

hcpctl set tag prj my-project env=prod owner=platform --org my-org

Purging State (Danger Zone)

If you need to completely reset a workspace's state (making Terraform "forget" all resources without destroying them in the cloud provider), you can use the purge state command.

This requires the exact Workspace ID (ws-...) to prevent accidental deletion.

hcpctl purge state ws-1234567890abcdef

Note: To bypass the interactive confirmation prompt, you must use the --my-resume-is-updated flag instead of the standard --batch flag.

Runs and Logs

Monitoring and managing Terraform runs is a common task. hcpctl provides commands to view runs, stream logs, and cancel stuck runs.

Viewing Runs

To list active runs (runs that are not in a final state like applied or errored) across your organization:

hcpctl get run --org my-org

To view runs for a specific workspace:

hcpctl get run --ws ws-1234567890abcdef

--ws accepts a workspace ID (ws-...).

You can also filter by status and workspace names in org scope:

hcpctl get run --org my-org --status planning,applying
hcpctl get run --org my-org --workspace-names app-prod,network-prod

Streaming Logs

You can view logs of a specific run, or logs from the current run of a workspace.

To stream logs for a specific run ID:

hcpctl logs run-1234567890abcdef

To stream logs for the current run of a workspace (name or ws-...):

hcpctl logs my-workspace --org my-org

By default, this streams the plan logs. To stream the apply logs, use the -a or --apply flag:

hcpctl logs my-workspace --apply --org my-org

To follow output in real time, add -f / --follow:

hcpctl logs run-1234567890abcdef --follow

Watching a Workspace

If you are waiting for a workspace to trigger a run (e.g., from a VCS webhook), you can use the watch command. This will continuously monitor the workspace and automatically stream logs whenever a new run starts.

hcpctl watch ws my-workspace --org my-org

This is incredibly useful for CI/CD pipelines or when you've just pushed a commit and want to see the Terraform output immediately.

Purging Runs

Sometimes a workspace gets stuck because of a queued run that is waiting for confirmation, or a run that has hung. You can use purge run to cancel or discard all pending runs blocking a workspace.

hcpctl purge run my-workspace --org my-org

This will:

Find all pending runs (queued, planning, etc.).
Ask for confirmation.
Cancel actively executing runs and discard queued runs.

You can use --dry-run to see what would be cancelled without actually doing it.

Managing Users and Teams

hcpctl provides administrative commands to manage users, teams, and invitations within your HCP Terraform organization. This is especially useful for onboarding new team members or auditing access.

Listing Organization Members

To see all members in your organization:

hcpctl get org-member --org my-org

Filtering Members

You can filter members by their email address or their current status (active or invited):

# Find a specific user
hcpctl get org-member -f "alice@example.com" --org my-org

# List all pending invitations
hcpctl get org-member --status invited --org my-org

Managing Teams

To list all teams in your organization:

hcpctl get team --org my-org

You can also filter teams by name:

hcpctl get team -f "platform" --org my-org

Inviting Users

You can invite a new user to your organization and optionally assign them to specific teams immediately.

hcpctl invite --email new.user@example.com --org my-org

To invite a user and add them to the "Developers" and "Platform" teams:

hcpctl invite --email new.user@example.com --teams "Developers,Platform" --org my-org

--teams accepts comma-separated team references (name or ID).

Removing Users

To remove a user from the organization, you can use their email address or their membership ID (ou-...):

hcpctl delete org-member old.user@example.com --org my-org

Skip confirmation with -y/--yes (or global --batch mode):

hcpctl delete org-member old.user@example.com --org my-org --yes

Viewing VCS Connections (OAuth Clients)

When setting up workspaces that connect to version control systems (like GitHub or GitLab), you often need the OAuth Client ID. You can list all configured VCS connections in your organization:

hcpctl get oc --org my-org

This will display the names, IDs (oc-...), and the service provider (e.g., github, gitlab_hosted) for each connection.

Command-Line Help for `hcpctl`

This document contains the help content for the hcpctl command-line program.

Command Overview:

`hcpctl`

Explore HCP Terraform / Terraform Enterprise resources

Usage: hcpctl [OPTIONS] <COMMAND>

HOST RESOLUTION:

The host is resolved in the following order (first match wins):

CLI argument (-H, --host)
Environment variable: TFE_HOSTNAME
Active context (from --context, HCPCTL_CONTEXT env, or current-context)
Credentials file (~/.terraform.d/credentials.tfrc.json):
- If 1 host configured: use it automatically
- If multiple hosts: interactive selection (or error in batch mode)

TOKEN RESOLUTION:

The API token is resolved in the following order (first match wins):

CLI argument (-t, --token)
Environment variables (in order): HCP_TOKEN, TFC_TOKEN, TFE_TOKEN
Active context
Credentials file (~/.terraform.d/credentials.tfrc.json) Token is read from the entry matching the resolved host.

CONTEXT:

Contexts store connection defaults (host, token, org) for quick switching:

- hcpctl config set-context prod --host app.terraform.io --org my-org
- hcpctl config use-context prod

Resolution (first match wins):

- Host:  -H flag → TFE_HOSTNAME env → context → credentials file
- Token: -t flag → HCP_TOKEN/TFC_TOKEN/TFE_TOKEN env → context → credentials file
- Org:   --org flag → context

EXAMPLES:

hcpctl get org # List all organizations
hcpctl get ws --org myorg # List workspaces in organization
hcpctl get ws myws --org myorg # Get workspace details
hcpctl -H app.terraform.io get ws # Use specific host
hcpctl -c prod get ws # Use 'prod' context

Subcommands:

get — Get resources (organizations, projects, workspaces)
delete — Delete resources
purge — Purge resources (destructive operations with mandatory confirmation)
download — Download resources (configuration files, etc.)
logs — View logs for a run (plan or apply)
watch — Watch resources for changes
invite — Invite a user to an organization
set — Set resource properties (assign workspace to project, etc.)
config — Manage connection contexts for multiple TFE/HCP instances
update — Update hcpctl to the latest version

Options:

-c, --context <CONTEXT> — Use a specific named context (overrides current-context)
-H, --host <HOST> — TFE/HCP host URL (falls back to TFE_HOSTNAME env var or credentials file)
-t, --token <TOKEN> — API token (overrides env vars and credentials file)
-l, --log-level <LOG_LEVEL> — Log level (error, warn, info, debug, trace)

Default value: warn
-b, --batch — Batch mode - no interactive prompts, no spinners

Default value: false
--no-header — Omit header row in table/CSV output

Default value: false

`hcpctl get`

Get resources (organizations, projects, workspaces)

Usage: hcpctl get <COMMAND>

Subcommands:

org — Get organizations
prj — Get projects
ws — Get workspaces
oc — Get OAuth clients (VCS connections)
run — Get runs (active runs by default - non_final states)
team — Get teams in an organization
org-member — Get organization members
team-access — Get team project access bindings
tag — Get tags (org-level, workspace, or project)

`hcpctl get org`

Get organizations

Usage: hcpctl get org [OPTIONS] [NAME]

Command Aliases: orgs, organization, organizations

hcpctl - kubectl-style CLI for HCP Terraform