tfc-workspace-runs

created	"2025-12-16T00:00:00.000Z"
modified	"2026-05-09T00:00:00.000Z"
reviewed	"2026-04-25T00:00:00.000Z"
name	tfc-workspace-runs
description	List TFC runs across known workspaces (github, sentry, gcp, onelogin, twingate). Use when checking TFC status or listing runs by workspace. Requires TFE_TOKEN.
user-invocable	false
allowed-tools	Bash, Read

Terraform Cloud Workspace Runs

Convenience wrapper for quick access to runs in Forum Virium Helsinki Terraform Cloud workspaces.

When to Use This Skill

Use this skill when...	Use a sibling instead when...
Listing runs for an FVH workspace by shorthand (github, sentry, gcp, onelogin, twingate)	Listing runs for a non-FVH workspace or arbitrary ID (tfc-list-runs)
Sweeping latest runs across every FVH workspace at once	Filtering by status, operation, or source with full options (tfc-list-runs)
Checking which FVH workspaces have in-progress runs	Reading detailed status for a single known run (tfc-run-status)
Discovering the right run ID before drilling into logs/plan JSON	Reading plan/apply log content for a specific run (tfc-run-logs)

Prerequisites

export TFE_TOKEN="your-api-token"        # User or team token
export TFE_ADDRESS="app.terraform.io"    # Optional

Known Workspaces

Shorthand	Full Workspace Name
github	infrastructure-github
sentry	infrastructure-sentry
gcp	infrastructure-gcp
onelogin	infrastructure-onelogin
twingate	infrastructure-twingate

Core Commands

Quick List Runs

#!/bin/bash
set -euo pipefail

TOKEN="${TFE_TOKEN:?TFE_TOKEN not set}"
BASE_URL="https://${TFE_ADDRESS:-app.terraform.io}/api/v2"
ORG="ForumViriumHelsinki"

# Map shorthand to full workspace name
case "${1:-}" in
  github)   WORKSPACE="infrastructure-github" ;;
  sentry)   WORKSPACE="infrastructure-sentry" ;;
  gcp)      WORKSPACE="infrastructure-gcp" ;;
  onelogin) WORKSPACE="infrastructure-onelogin" ;;
  twingate) WORKSPACE="infrastructure-twingate" ;;
  *)
    echo "Usage: $0 <workspace> [limit]"
    echo "Workspaces: github, sentry, gcp, onelogin, twingate"
    exit 1
    ;;
esac

LIMIT="${2:-10}"

# Get workspace ID
WS_ID=$(curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/organizations/$ORG/workspaces/$WORKSPACE" | \
  jq -r '.data.id')

# List runs
echo "Recent runs for $WORKSPACE:"
echo ""

curl -sf --header "Authorization: Bearer $TOKEN" \
  "$BASE_URL/workspaces/$WS_ID/runs?page[size]=$LIMIT&include=plan" | \
  jq -r '
    ["RUN_ID", "STATUS", "+", "~", "-", "CREATED", "MESSAGE"],
    (.data[] |
      .relationships.plan.data.id as $pid |
      [
        .id,
        .attributes.status,
        ((.included[] | select(.id == $pid) | .attributes."resource-additions") // 0 | tostring),
        ((.included[] | select(.id == $pid) | .attributes."resource-changes") // 0 | tostring),
        ((.included[] | select(.id == $pid) | .attributes."resource-destructions") // 0 | tostring),
        .attributes."created-at"[0:16],
        (.attributes.message // "No message")[0:30]
      ]
    ) | @tsv' | column -t

One-Liner Examples

# GCP workspace - recent runs
curl -sf -H "Authorization: Bearer $TFE_TOKEN" \
  "https://app.terraform.io/api/v2/organizations/ForumViriumHelsinki/workspaces/infrastructure-gcp" | \
  jq -r '.data.id' | \
  xargs -I{} curl -sf -H "Authorization: Bearer $TFE_TOKEN" \
    "https://app.terraform.io/api/v2/workspaces/{}/runs?page[size]=5" | \
  jq -r '.data[] | "\(.id) | \(.attributes.status) | \(.attributes."created-at"[0:16])"'

# GitHub workspace - failed runs only
curl -sf -H "Authorization: Bearer $TFE_TOKEN" \
  "https://app.terraform.io/api/v2/organizations/ForumViriumHelsinki/workspaces/infrastructure-github" | \
  jq -r '.data.id' | \
  xargs -I{} curl -sf -H "Authorization: Bearer $TFE_TOKEN" \
    "https://app.terraform.io/api/v2/workspaces/{}/runs?filter[status]=errored" | \
  jq -r '.data[] | "\(.id) | \(.attributes.status) | \(.attributes.message)"'

Get Latest Run for Each Workspace

#!/bin/bash
set -euo pipefail

TOKEN="${TFE_TOKEN:?TFE_TOKEN not set}"
BASE_URL="https://${TFE_ADDRESS:-app.terraform.io}/api/v2"
ORG="ForumViriumHelsinki"

WORKSPACES="infrastructure-github infrastructure-sentry infrastructure-gcp infrastructure-onelogin infrastructure-twingate"

echo "Latest run for each workspace:"
echo ""

for WS in $WORKSPACES; do
  WS_ID=$(curl -sf --header "Authorization: Bearer $TOKEN" \
    "$BASE_URL/organizations/$ORG/workspaces/$WS" | jq -r '.data.id')

  LATEST=$(curl -sf --header "Authorization: Bearer $TOKEN" \
    "$BASE_URL/workspaces/$WS_ID/runs?page[size]=1" | \
    jq -r '.data[0] | "\(.id) | \(.attributes.status) | \(.attributes."created-at"[0:16])"')

  echo "$WS: $LATEST"
done

Check for In-Progress Runs

#!/bin/bash
set -euo pipefail

TOKEN="${TFE_TOKEN:?TFE_TOKEN not set}"
BASE_URL="https://${TFE_ADDRESS:-app.terraform.io}/api/v2"
ORG="ForumViriumHelsinki"

WORKSPACES="infrastructure-github infrastructure-sentry infrastructure-gcp infrastructure-onelogin infrastructure-twingate"

echo "Checking for in-progress runs..."
echo ""

for WS in $WORKSPACES; do
  WS_ID=$(curl -sf --header "Authorization: Bearer $TOKEN" \
    "$BASE_URL/organizations/$ORG/workspaces/$WS" | jq -r '.data.id')

  IN_PROGRESS=$(curl -sf --header "Authorization: Bearer $TOKEN" \
    "$BASE_URL/workspaces/$WS_ID/runs?filter[status_group]=non_final&page[size]=5" | \
    jq -r '.data | length')

  if [ "$IN_PROGRESS" -gt 0 ]; then
    echo "$WS: $IN_PROGRESS run(s) in progress"
    curl -sf --header "Authorization: Bearer $TOKEN" \
      "$BASE_URL/workspaces/$WS_ID/runs?filter[status_group]=non_final" | \
      jq -r '.data[] | "  - \(.id): \(.attributes.status)"'
  fi
done

Quick Reference

Get Workspace ID

# Generic pattern
curl -sf -H "Authorization: Bearer $TFE_TOKEN" \
  "https://app.terraform.io/api/v2/organizations/ForumViriumHelsinki/workspaces/infrastructure-gcp" | \
  jq -r '.data.id'

Workspace URLs (for reference)

• GitHub: https://app.terraform.io/app/ForumViriumHelsinki/workspaces/infrastructure-github
• Sentry: https://app.terraform.io/app/ForumViriumHelsinki/workspaces/infrastructure-sentry
• GCP: https://app.terraform.io/app/ForumViriumHelsinki/workspaces/infrastructure-gcp
• OneLogin: https://app.terraform.io/app/ForumViriumHelsinki/workspaces/infrastructure-onelogin
• Twingate: https://app.terraform.io/app/ForumViriumHelsinki/workspaces/infrastructure-twingate

Integration with Other Skills

Get logs for latest GCP run

# Get latest run ID
RUN_ID=$(curl -sf -H "Authorization: Bearer $TFE_TOKEN" \
  "https://app.terraform.io/api/v2/organizations/ForumViriumHelsinki/workspaces/infrastructure-gcp" | \
  jq -r '.data.id' | \
  xargs -I{} curl -sf -H "Authorization: Bearer $TFE_TOKEN" \
    "https://app.terraform.io/api/v2/workspaces/{}/runs?page[size]=1" | \
  jq -r '.data[0].id')

# Then use tfc-run-logs skill to get logs
echo "Use tfc-run-logs with run ID: $RUN_ID"

Quick status check for all workspaces

# Combine with tfc-run-status for detailed info on specific runs

Customization

To add more workspaces, update the case statement in the script:

case "${1:-}" in
  github)   WORKSPACE="infrastructure-github" ;;
  sentry)   WORKSPACE="infrastructure-sentry" ;;
  gcp)      WORKSPACE="infrastructure-gcp" ;;
  onelogin) WORKSPACE="infrastructure-onelogin" ;;
  twingate) WORKSPACE="infrastructure-twingate" ;;
  # Add more here:
  newworkspace) WORKSPACE="infrastructure-newworkspace" ;;
  *)
    echo "Usage: $0 <workspace>"
    exit 1
    ;;
esac

See Also

• tfc-list-runs: Full-featured run listing with all filters
• tfc-run-logs: Get plan/apply logs for a specific run
• tfc-run-status: Quick status check for a run
• tfc-plan-json: Get structured plan JSON output
• terraform-workspace-manager: Workspace orchestration and run management