terraui 0.1.4

Local-first control plane for Terraform & Terragrunt — inventory, plan/apply, drift, locks and a cloud shell, in one UI.

TerraUi

A local-first control plane for Terraform & Terragrunt. Point it at the folder that holds all your IaC repos; it discovers every unit, and gives one web UI to inventory stacks, run plan/apply/destroy (streamed live), detect drift, read state and locks, browse the Terragrunt dependency graph, open a cloud shell, and ask an AI assistant.

This repo implements the TerraUi.dc.html design (the product surface) plus the backend from BACKEND_SPEC.md. It ships as a Python package with the compiled frontend bundled and served at /.

pip install -e .            # from this repo (Python 3.10+)
cd ~/acme/infra             # the folder containing your IaC repos
terraui start               # discovers everything, opens http://localhost:8787

No IaC in the current folder? terraui start falls back to a fully-populated demo dataset (the one from the design) so you can explore the whole UI.

Cloud SDK setup (gcloud / aws / az)

TerraUi shells out to your existing cloud CLIs — it never stores credentials. On first terraui start it runs a read-only check of the providers your stacks actually use and, if anything is missing, points you at terraui setup:

terraui setup            # per provider: detect → offer install → offer login

setup is per-provider and skippable — if you only use GCP, skip AWS and Azure and configure them later. It shows the exact install/login command before running it and asks for confirmation; nothing happens silently. GCP runs both required logins (gcloud auth login for the CLI and gcloud auth application-default login for the Terraform provider).

CLI

terraui start [PATH]        Local mode: scan PATH (default cwd), serve UI + executor
    --port 8787             Port (default 8787)
    --scan ./live ./mods    Extra roots to scan
    --no-open               Don't auto-open the browser
    --shell powershell|zsh|bash
    --drift-interval 30m    Background drift cadence (0 = off)
    --demo                  Force the bundled demo dataset
    --check                 Run interactive cloud-SDK setup before serving
    --skip-checks           Skip the cloud-SDK status check

terraui setup [PATH]        Detect / install / authenticate cloud SDKs (per-provider, skippable)
    --providers aws,gcp,azure   Limit to specific providers
    --yes                       Non-interactive (install only; skip browser logins)

terraui scan [PATH] --json  Print discovered units as JSON (CI / debug)
terraui server  --config …  Team mode (scaffold — see BACKEND_SPEC §11)
terraui agent   --server …  Remote executor (scaffold)

What's implemented

Area	Status
Discovery (HCL walk, backend/provider/deps parse, Terragrunt DAG)	✅ discovery/
Execution engine (flag model → build_command, streamed over WS, persisted)	✅ execution/, store/
Cloud auth probes (AWS / GCP-with-ADC / Azure)	✅ clouds/
State & lock read (terraform state list, acquire/release)	✅ state/
Drift (per-stack snapshots; demo data, live scan scaffolded)	◑ drift endpoint
Cloud Shell PTY (pywinpty / ptyprocess, subprocess fallback)	✅ shell/
AI assistant (Claude claude-haiku-4-5 proxy + offline fallback)	✅ ai/
Frontend bundle (all views, drawer, flag modal, toast)	✅ web/index.html
VCS webhooks, server/agent mode, RBAC, policy gates	☐ scaffolded (§10–11)

The command the UI previews is exactly the command the executor runs — buildCmdStr (frontend) and build_command (backend) are kept identical and unit-tested against the spec example (terragrunt run-all plan -var-file=env/prod.tfvars --terragrunt-non-interactive).

Architecture

Browser (web/index.html)
  REST  /api/*            inventory, runs, drift, locks, graph, clouds, ai
  WS    /ws/run/{id}      live plan/apply output
  WS    /ws/term/{sess}   PTY terminal
        │
FastAPI app (server/app.py)
  discovery · execution · clouds · state · drift · ai · store
        │ subprocess (user's shell)
        ▼
terraform / terragrunt / aws / gcloud / az  on the local machine

Develop

pip install -e ".[dev,pty]"
pytest                       # command builder, discovery, API smoke tests
terraui start --demo         # run the UI against the demo dataset

The AI assistant proxies to Claude when ANTHROPIC_API_KEY is set (model claude-haiku-4-5); otherwise it returns grounded canned answers. The key never reaches the browser.

Security

Local mode binds to 127.0.0.1. No secrets are stored — TerraUi shells out using the cloud SDK credential chains already on your machine. Commands are built from a structured flag model and passed as argv (never shell-interpolated); the action is checked against an allow-list. Secrets are redacted from streamed logs before they are persisted. See BACKEND_SPEC.md §14 for the full model.