managing-terraform-cloud

name	managing-terraform-cloud
description	Use when working with Terraform Cloud — terraform Cloud workspace and run management. Covers workspace configuration, run triggers, variable sets, policy checks (Sentinel/OPA), VCS integration, state management, and team access controls. Use when managing Terraform Cloud workspaces, inspecting runs, reviewing policy failures, or auditing organization settings.
connection_type	terraform-cloud
preload	false

Terraform Cloud Management Skill

Manage Terraform Cloud workspaces, runs, policies, and organization settings via the TFC API.

MANDATORY: Discovery-First Pattern

Always inspect organization and workspace state before taking action.

Phase 1: Discovery

#!/bin/bash
TFC_TOKEN="${TFC_TOKEN:?TFC_TOKEN required}"
TFC_ORG="${TFC_ORG:?TFC_ORG required}"
API="https://app.terraform.io/api/v2"
AUTH="Authorization: Bearer $TFC_TOKEN"

echo "=== Organization Details ==="
curl -s -H "$AUTH" "$API/organizations/$TFC_ORG" | jq '{name: .data.attributes.name, email: .data.attributes.email, plan: .data.attributes."plan-name"}'

echo ""
echo "=== Workspaces (top 20) ==="
curl -s -H "$AUTH" "$API/organizations/$TFC_ORG/workspaces?page[size]=20" | jq -r '.data[] | "\(.attributes.name) | \(.attributes."terraform-version") | \(.attributes."resource-count") resources | locked=\(.attributes.locked)"'

echo ""
echo "=== Recent Runs ==="
curl -s -H "$AUTH" "$API/organizations/$TFC_ORG/runs?page[size]=10" | jq -r '.data[] | "\(.attributes.status) | \(.relationships.workspace.data.id) | \(.attributes."created-at")"' 2>/dev/null | head -10

Phase 2: Analysis

#!/bin/bash
TFC_TOKEN="${TFC_TOKEN:?TFC_TOKEN required}"
TFC_ORG="${TFC_ORG:?TFC_ORG required}"
API="https://app.terraform.io/api/v2"
AUTH="Authorization: Bearer $TFC_TOKEN"
WS_NAME="${1:?Workspace name required}"

WS_ID=$(curl -s -H "$AUTH" "$API/organizations/$TFC_ORG/workspaces/$WS_NAME" | jq -r '.data.id')

echo "=== Workspace Config ==="
curl -s -H "$AUTH" "$API/workspaces/$WS_ID" | jq '{name: .data.attributes.name, execution_mode: .data.attributes."execution-mode", auto_apply: .data.attributes."auto-apply", tf_version: .data.attributes."terraform-version", vcs: .data.attributes."vcs-repo"}'

echo ""
echo "=== Variables ==="
curl -s -H "$AUTH" "$API/workspaces/$WS_ID/vars" | jq -r '.data[] | "\(.attributes.key) = \(if .attributes.sensitive then "***" else .attributes.value end) [\(.attributes.category)]"' | head -20

echo ""
echo "=== Latest Run ==="
curl -s -H "$AUTH" "$API/workspaces/$WS_ID/runs?page[size]=1" | jq '.data[0] | {status: .attributes.status, created: .attributes."created-at", plan_adds: .attributes."resource-additions", plan_changes: .attributes."resource-changes", plan_destroys: .attributes."resource-destructions"}'

 
 
RUN_ID=$(curl -s -H   | jq -r )
curl -s -H   | jq -r 

Output Rules

• TOKEN EFFICIENCY: Target <=50 lines per output
• Always redact sensitive variable values
• Summarize run history rather than listing every run
• Use workspace name filters to narrow queries

Safety Rules

• NEVER trigger applies without explicit confirmation
• Always use plan-only runs for investigation
• Check policy results before recommending apply
• Lock workspaces before manual state operations
• Verify VCS branch before triggering runs

Output Format

Present results as a structured report:

Managing Terraform Cloud Report
═══════════════════════════════
Resources discovered: [count]

Resource       Status    Key Metric    Issues
──────────────────────────────────────────────
[name]         [ok/warn] [value]       [findings]

Summary: [total] resources | [ok] healthy | [warn] warnings | [crit] critical
Action Items: [list of prioritized findings]

Target ≤50 lines of output. Use tables for multi-resource comparisons.

Anti-Hallucination Rules

1. NEVER assume resource names — always discover via CLI/API in Phase 1 before referencing in Phase 2.
2. NEVER fabricate metric names or dimensions — verify against the service documentation or --help output.
3. NEVER mix CLI commands between service versions — confirm which version/API you are targeting.
4. ALWAYS use the discovery → verify → analyze chain — every resource referenced must have been discovered first.
5. ALWAYS handle empty results gracefully — an empty response is valid data, not an error to retry.

Counter-Rationalizations

Shortcut	Counter	Why
"I'll skip discovery and check known resources"	Always run Phase 1 discovery first	Resource names change, new resources appear — assumed names cause errors
"The user only asked for a quick check"	Follow the full discovery → analysis flow	Quick checks miss critical issues; structured analysis catches silent failures
"Default configuration is probably fine"	Audit configuration explicitly	Defaults often leave logging, security, and optimization features disabled
"Metrics aren't needed for this"	Always check relevant metrics when available	API/CLI responses show current state; metrics reveal trends and intermittent issues
"I don't have access to that"	Try the command and report the actual error	Assumed permission failures prevent useful investigation; actual errors are informative