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	List/filter organizations
	org-member	List/filter organization members by email/status
	prj	List/filter/sort projects, show workspace counts/names/IDs/details
	run	List active runs (non-final states), filter by status/workspace/project, fetch subresources (events, plan, apply), stream/download logs
	tag	List tags at org level or per workspace/project (tag ws, tag prj)
	team	List/filter teams in organization
	team-access	List/filter/sort team-project access assignments
	ws	List/filter/sort workspaces, group by org/project, filter by pending runs, fetch subresources (current-run, current-state-version, current-configuration-version, current-assessment-result), show run history with phase durations (--runs), show state version history (--states)
set	ws	Modify workspace properties (assign to project, set description)
	tag ws	Set tags on a workspace (key-only or key=value)
	tag prj	Set tags on a project (key=value)
delete	org-member	Remove user from organization (by ID or email)
	tag ws	Remove tags from a workspace
	tag prj	Remove tags from a project
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
download	cv	Download configuration version archive for a workspace
invite	—	Invite user to organization, optionally assign to teams
purge	run	Cancel/discard pending runs blocking a workspace (supports dry-run)
	state	Zero out all resources from workspace state (with mandatory confirmation)
context	—	Manage named connection contexts (set, use, list, current, delete, show)
update	—	Self-update to latest version

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

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

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

License

GPL-3.0 license