infra-guide

Overview

infra-guide is a free, open-source CLI and interactive TUI for Terraform and OpenTofu. It combines a guided menu for beginners with direct subcommands for production use — both powered by the same engine.

Beyond being a menu wrapper, infra-guide adds capabilities that raw Terraform doesn't include: Doctor diagnostics, a built-in security policy engine, a local browser command center, cost insight from plan JSON, drift detection, 5 visual themes, shell completion, and CI/CD pipeline mode.

Prerequisites

Before installing infra-guide, you need the following on your system:

Install Terraform or OpenTofu

You only need one of these — infra-guide auto-detects which one is available.

Installation

pip (standard)

The simplest way — works on any system with Python 3.8+.

pip install infra-guide

pipx (recommended)

pipx installs infra-guide in an isolated environment so it never conflicts with other Python packages.

# Install pipx if you don't have it
pip install pipx

# Install infra-guide
pipx install infra-guide

From source

git clone https://github.com/cloudgrains/infra-guide.git
cd infra-guide
pip install .

Verify installation

infra-guide --version

Quick Start

Run these four commands from any directory containing Terraform or OpenTofu configuration files to get oriented immediately.

Doctor Mode

Doctor mode runs a full workspace health audit. It validates your configuration, checks the backend, counts variables, verifies provider locks, and — optionally — detects infrastructure drift, all in a single command.

# Basic health check
infra-guide doctor

# Health check + drift detection
infra-guide doctor --with-drift

What it checks

Example output

$ infra-guide doctor
⚕ Workspace Health
✔ Terraform v1.6.0       detected
✔ Backend configured     S3
✔ Providers locked       .terraform.lock.hcl
✔ Variables set          10 / 10
⚠ Drift detected        2 resources changed

Run `infra-guide plan` to see full diff

Policy Checks

infra-guide ships a built-in security policy engine. Run infra-guide policy to check your Terraform plan against six security rules — no external tools required.

# Check against saved plan file
infra-guide policy --plan-file tfplan.json

# Run policy check interactively
infra-guide policy

Built-in policies

Web Command Center

infra-guide web launches a local browser interface powered by the same backend as the TUI. Everything you can do in the terminal, you can do from a browser tab.

# Start on default port 8765
infra-guide web

# Use a custom port
infra-guide web --port 9000

# Start server without opening browser
infra-guide web --no-browser

The web UI opens automatically at http://localhost:8765. It shows a dashboard with your workspace status, recent commands, and buttons to run all infra-guide operations.

Drift Detection

Drift occurs when someone modifies cloud resources directly (via the console, CLI, or another tool) without updating Terraform. infra-guide can detect this automatically.

# Standalone drift check
infra-guide drift

# Combined with health diagnostics
infra-guide doctor --with-drift

When drift is detected, infra-guide shows which resources changed and what properties differ from the state file. From there, you can run infra-guide plan to see the full diff and decide whether to apply or import the manual changes.

Cost Insight

When you apply with a saved plan file, infra-guide analyses the plan JSON and surfaces AWS cost-impact hints before any changes run. This gives you a rough estimate of what the change will cost before it's irreversible.

# 1. Save a plan
infra-guide plan --out tfplan

# 2. Apply with cost hints shown automatically
infra-guide apply --plan-file tfplan --yes

Themes

infra-guide ships with five visual themes. Your selected theme persists across sessions.

Switching themes

# Set theme (persists across sessions)
infra-guide theme --set neon

# List available themes
infra-guide theme --list

# Reset to default (aurora)
infra-guide theme --reset

Shell Completion

infra-guide supports tab completion for bash, zsh, and fish. Setup is a one-time operation per shell.

bash

infra-guide completion bash >> ~/.bashrc
source ~/.bashrc

zsh

infra-guide completion zsh >> ~/.zshrc
source ~/.zshrc

fish

infra-guide completion fish > ~/.config/fish/completions/infra-guide.fish

After setup, press Tab after typing infra-guide to see available subcommands, flags, and their descriptions.

Command History & Favorites

infra-guide logs all commands you run and lets you pin frequently-used ones as favorites.

# View recent command history
infra-guide history

# View favorites only
infra-guide history --favorites

From the history view you can re-run any previous command, add it to favorites, or remove old entries. Favorites are accessible from the TUI main menu.

CI/CD Mode

infra-guide cicd runs a pipeline-safe init → validate → plan sequence in non-interactive mode with machine-readable exit codes. No prompts, no TUI, no user interaction required.

# Run CI/CD pipeline
infra-guide cicd

# Exit codes:
# 0 — success, plan shows no changes
# 1 — error (config/init failure)
# 2 — success, plan shows changes (standard Terraform behavior)

GitHub Actions example

- name: infra-guide CI
  run: |
    pip install infra-guide
    infra-guide cicd
  env:
    TF_VAR_region: us-east-1

Workspaces

Workspaces let you manage multiple environments (dev, staging, prod) from the same configuration. infra-guide wraps Terraform's workspace commands with a cleaner interface.

# List all workspaces (current marked with *)
infra-guide workspace --list

# Create a new workspace
infra-guide workspace --new staging

# Switch to a workspace
infra-guide workspace --select production

# Delete a workspace
infra-guide workspace --delete old-env

State Explorer

Explore your Terraform state file without editing it directly. The state explorer shows resources in list, tree, or detail view.

# Overview — resource count by type
infra-guide state

# Tree view — hierarchical by resource type
infra-guide state --tree

# Detailed view of one resource
infra-guide state --show aws_instance.web

State explorer is read-only — it never modifies your state file. Use it to audit what Terraform knows about, find resource addresses, and understand your current infrastructure without running terraform state list manually.

All Commands

Complete reference for every infra-guide subcommand.

FAQ

Contributing

Contributions are welcome. Here's how to get started:

# 1. Fork and clone
git clone https://github.com/cloudgrains/infra-guide.git
cd infra-guide

# 2. Create virtual environment
python3 -m venv venv
source venv/bin/activate

# 3. Install in dev mode
pip install -e ".[dev]"

# 4. Run tests
pytest

# 5. Format code
black infra_guide/

Open a Pull Request from your fork targeting the main branch. Please include test coverage for new features.