tfc-api

name	tfc-api
description	Query Terraform Cloud (TFC) workspaces, runs, plans, logs, and team/project access via API. Use when inspecting TFC workspace state, checking run history, analyzing plan output, reviewing apply logs, managing team permissions, or diagnosing access issues in a Terraform Cloud organization.

Terraform Cloud API

CRITICAL DIRECTIVE: Always prefer using the terrapyne CLI (e.g. uv run terrapyne or tfc) for TFC operations. Only fall back to raw API calls (curl/httpie) or the bash scripts listed below if terrapyne is not available in the environment or lacks the required functionality.

Example: Instead of ./scripts/list-runs.sh, use uv run terrapyne run list. Instead of manual curl for workspace discovery, use uv run terrapyne workspace list or tfc project find.

Query TFC workspaces, runs, logs, and team permissions without leaving the terminal.

Authentication

All scripts use a two-tier token resolution: TFC_TOKEN env var takes precedence, falling back to ~/.terraform.d/credentials.tfrc.json. This matters because personal tokens often lack org-level permissions (e.g. team management) that automation tokens have.

# Option 1: Environment variable (preferred for automation/elevated ops)
export TFC_TOKEN=<your-token>

# Option 2: Credentials file (automatic fallback)
# ~/.terraform.d/credentials.tfrc.json — used if TFC_TOKEN is unset

# Typical workflow: source an env file with the automation token
 /tmp/env.sh