infra-guide

A product-grade CLI and interactive command center for Terraform and OpenTofu. Blends guide-first workflows, direct subcommands, workspace diagnostics, policy checks, and automation-friendly commands — so the tool works equally well for learning and day-to-day operations.

Features

• Interactive TUI dashboard — themed readiness panel, workspace info, recent commands, and favorites
• Direct CLI subcommands — init, plan, apply, destroy, fmt, state, workspace, cicd, output, policy, and more
• Doctor mode — workspace health checks with actionable recommendations and optional drift detection
• Policy checks — built-in security policy engine (no-public-S3, open security groups, missing tags, encryption, versioning)
• Web command center — launch a local browser UI (infra-guide web) powered by the same backend as the TUI
• Themes — hacker (default CRT/phosphor shell), aurora, sunset, forest, mono, neon — persisted across sessions
• Shell completion — one-line setup for bash, zsh, and fish
• Update notifications — background PyPI check after each command, cached for 24 h
• Cost insight — analyzes saved plan JSON for AWS cost-impact hints before apply
• Command history and favorites — rerun support inside the TUI
• Local-only — no telemetry, no credential handling, no cloud calls beyond what your IaC tool makes

Installation

pip install infra-guide
# or
pipx install infra-guide

Quick start

# interactive mode
infra-guide

# direct CLI
infra-guide doctor
infra-guide plan --out tfplan
infra-guide apply --plan-file tfplan --yes

Shell completion

# bash — add to ~/.bashrc
eval "$(infra-guide completion bash)"

# zsh — add to ~/.zshrc
eval "$(infra-guide completion zsh)"

# fish — add to ~/.config/fish/config.fish
infra-guide completion fish | source

Commands

Usage examples

Doctor and status

infra-guide status                # fast workspace panel
infra-guide doctor                # full health check
infra-guide doctor --with-drift   # health check + drift detection

Plan, apply, and destroy

infra-guide plan --out tfplan
infra-guide apply --plan-file tfplan --yes
infra-guide destroy --yes

# pass raw flags through to the IaC tool after --
infra-guide plan -- --target=module.network
infra-guide init -- --backend-config=env/dev.backend.hcl

Policy as code

# check the current directory against built-in security policies
infra-guide policy

# check a saved plan JSON
infra-guide plan --out tfplan.json
infra-guide policy --plan-file tfplan.json

Policies included out of the box:

Themes

infra-guide theme --list
infra-guide theme --set hacker    # hacker | aurora | sunset | forest | mono | neon

Output values

infra-guide output                 # all outputs
infra-guide output bucket_name     # single output
infra-guide output --json          # raw JSON

State exploration

infra-guide state                  # overview
infra-guide state --list           # flat list
infra-guide state --tree           # grouped tree view
infra-guide state --detail aws_instance.web

Web command center

infra-guide web               # opens http://localhost:8765
infra-guide web --port 9000
infra-guide web --no-browser  # server only

Workspace management

infra-guide workspace --list
infra-guide workspace --create dev
infra-guide workspace --select prod
infra-guide workspace --delete staging

CI/CD mode

infra-guide cicd
infra-guide cicd --skip-init
infra-guide cicd --skip-validation

Suggested workflow

infra-guide doctor               # 1. understand workspace health
infra-guide init                 # 2. initialize if needed
infra-guide plan --out tfplan    # 3. preview and save
infra-guide policy               # 4. check against security policies
infra-guide apply --plan-file tfplan --yes  # 5. apply

Security and privacy

• No telemetry
• No credential handling inside infra-guide
• Network calls: only the background PyPI version check (cached 24 h, skipped on --no-color)
• Open source and auditable

Development

git clone https://github.com/iamtejas23/infra-guide.git
cd infra-guide
python3 -m venv venv && source venv/bin/activate
pip install -e ".[dev]"
pytest
black infra_guide/
flake8 infra_guide/ --max-line-length=100

Release to PyPI

Version lives in two files that must stay identical: pyproject.toml and infra_guide/__init__.py. After your feature work is committed and the tree is clean, bump with npm-style commands. Each command takes the current version, adds exactly one patch/minor/major step, refuses if that number already exists on PyPI or as a git tag, then commits, tags vX.Y.Z, and pushes. GitHub Actions publishes https://pypi.org/project/infra-guide/.

# see local vs git tag vs PyPI
npm run version

# preview the next number (no commit, no tag, no push)
npm run patch -- --dry-run
npm run minor -- --dry-run
npm run major -- --dry-run

# 0.9.0 -> 0.9.1   (bugfix)
npm run patch

# 0.9.1 -> 0.10.0  (feature)
npm run minor

# 0.10.0 -> 1.0.0  (breaking)
npm run major

Same commands without npm:

python3 scripts/release.py --show
python3 scripts/release.py patch --dry-run
python3 scripts/release.py patch
python3 scripts/release.py minor
python3 scripts/release.py major

Rules the script enforces:

• working tree must be clean (commit first)
• pyproject.toml version must match infra_guide/__init__.py
• next version must be current+1 for that part (no skipped numbers)
• next version must not already exist on PyPI or as vX.Y.Z
• if local is behind PyPI, it stops (sync first)
• if local is already ahead of PyPI, it stops (do not bump twice)

--no-push creates the commit and tag locally only. --offline skips the PyPI check.

Project structure

infra-guide/
├── infra_guide/
│   ├── cli.py               # entry point and argument parser
│   ├── ui.py                # Rich-based TUI
│   ├── runner.py            # subprocess wrapper
│   ├── detector.py          # tool detection (tofu / terraform)
│   ├── project_inspector.py # workspace metadata
│   ├── validators.py        # pre-flight checks
│   ├── drift_detector.py    # drift detection
│   ├── state_explorer.py    # state file browser
│   ├── workspace_manager.py # workspace CRUD
│   ├── policy_checker.py    # built-in policy engine
│   ├── cost_estimator.py    # plan cost analysis
│   ├── cicd.py              # CI/CD pipeline runner
│   ├── completion.py        # shell completion scripts
│   ├── update_checker.py    # background PyPI version check
│   ├── preferences.py       # theme and history persistence
│   ├── web.py               # browser command center
│   └── guides/              # command guide modules
├── scripts/
│   └── release.py           # npm-style patch/minor/major PyPI release
├── package.json             # npm run patch | minor | major
├── tests/
├── pyproject.toml
└── README.md

License

MIT — see LICENSE.