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