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