infra-guide v0.2.0 Documentation

Overview

infra-guide is a production-grade, interactive terminal UI (TUI) tool for Terraform and OpenTofu that combines beginner-friendly guidance with enterprise-level features. Learn infrastructure-as-code while using professional tools like drift detection, policy validation, and CI/CD integration.

✨ Features

Core Features

🎯 Auto-Detection

Automatically detects whether you have Terraform or OpenTofu installed

📚 Interactive Guides

Detailed explanations for each command before execution

🎨 Beautiful TUI

Rich, colorful interface with a modern dark theme

⚡ No Setup Required

No cloud credentials, no network calls, no telemetry

🛡️ Safety First

Confirmation prompts and warnings before destructive operations

📖 Beginner-Friendly

Best practices and common flags explained clearly

Enterprise Features (v0.2.0) 🆕

🔍 Drift Detection

Automatically detect when infrastructure has drifted from state

✅ Pre-Flight Validation

Comprehensive checks before executing commands

📦 State Explorer

Interactive browser for exploring state files with tree view

📁 Workspace Manager

Easy management of multiple environments

🚀 CI/CD Mode

Non-interactive pipeline mode for automation

📊 Resource Visualization

View resources by type with detailed statistics

📋 Prerequisites

Before installing infra-guide, ensure you have:

1. Python 3.8 or higher

python3 --version

2. Either Terraform OR OpenTofu (at least one required)

Terraform: Download and Install
OpenTofu: Download and Install

Note: No cloud credentials, API keys, or additional setup needed!

🚀 Installation

Option 1: Install with pipx (Recommended)

pipx installs Python applications in isolated environments, preventing dependency conflicts.

Install pipx if you don't have it:

sudo apt update
sudo apt install pipx

Install infra-guide:

pipx install git+https://github.com/cloudgrains-git/infra-guide.git

Run the tool:

infra-guide

Option 2: Install from Source

For development or to contribute to the project.

# Clone the repository
git clone https://github.com/cloudgrains-git/infra-guide.git
cd infra-guide

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

# Install the package
pip install .

Option 3: Install from PyPI (when published)

pipx install infra-guide

Coming Soon: This option will be available once the package is published to PyPI.

📖 Usage

Simply run the command from any directory containing Terraform/OpenTofu configuration files:

infra-guide

Navigation

Use number keys (1-5) to select menu options
Follow the on-screen prompts
Read the guides before executing commands
Confirm when prompted before any command execution

Example Workflow

Basic Workflow:

1. Initialize your project

Select option 1 (init)
Review the guide
Confirm execution

2. Validate configuration

Select option 5 (validate)
Run pre-flight checks
Fix any issues found

3. Preview changes

Select option 2 (plan)
Review the guide and understand what will change
Confirm execution

4. Apply changes

Select option 3 (apply)
Read warnings carefully
Confirm execution

Advanced Workflow:

1. Check for drift

Select option 6 (drift)
Detect changes made outside Terraform
Review drift report

2. Explore state

Select option 7 (state)
Browse current infrastructure
View resource tree and statistics

3. Manage environments

Select option 8 (workspace)
Switch between dev/staging/prod
Create or delete workspaces

4. Run CI/CD pipeline

Select option 9 (cicd)
Automated validation and planning
No user interaction required

🎯 Supported Commands

Command	Description	Risk Level	New in v0.2.0
`init`	Initialize working directory	🟢 Low	-
`plan`	Preview infrastructure changes	🟢 Low	-
`apply`	Create/update infrastructure	🟡 Medium	-
`destroy`	Delete all infrastructure	🔴 High	-
`validate`	Run pre-flight checks	🟢 Low	✅
`drift`	Detect infrastructure drift	🟢 Low	✅
`state`	Explore state file	🟢 Low	✅
`workspace`	Manage workspaces	🟡 Medium	✅
`cicd`	Run CI/CD pipeline	🟡 Medium	✅

💡 Feature Deep Dive

🔍 Drift Detection

Automatically detects when your actual infrastructure has diverged from the state file. This happens when changes are made outside of Terraform/OpenTofu (manual changes, other tools, etc.).

# In infra-guide, select option 6
# Shows which resources have drifted and what changed

✅ Pre-Flight Validation

Runs comprehensive checks before you execute commands:

Configuration file existence
Initialization status
Syntax validation
Code formatting
Backend configuration
Provider version locks
Required variables

📦 State Explorer

Interactive browser for your state file:

Overview: Total resources and types
Resource List: All resources with addresses
Tree View: Hierarchical visualization by resource type

📁 Workspace Manager

Easily manage multiple environments:

List all workspaces
Switch between workspaces
Create new workspaces
Delete unused workspaces
Visual indication of current workspace

🚀 CI/CD Pipeline Mode

Non-interactive mode perfect for automation:

Runs init → validate → plan automatically
Uses detailed exit codes
No user prompts
Designed for continuous integration

🔒 Security & Privacy

No Telemetry

We don't collect any data about your usage

No Network Calls

Works completely offline

No Credentials Required

Only wraps Terraform/OpenTofu CLI

Open Source

Fully transparent, auditable code

Local Execution

All commands run locally on your machine

🛠️ Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/cloudgrains-git/infra-guide.git
cd infra-guide

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Running Tests

pytest

Code Formatting

black infra_guide/

Type Checking

mypy infra_guide/

📁 Project Structure

infra-guide/
├── infra_guide/
│   ├── __init__.py          # Package initialization
│   ├── cli.py               # Main CLI entry point
│   ├── detector.py          # Tool detection logic
│   ├── ui.py                # UI components using rich
│   ├── runner.py            # Command execution
│   └── guides/
│       ├── __init__.py
│       ├── init.py          # Init command guide
│       ├── plan.py          # Plan command guide
│       ├── apply.py         # Apply command guide
│       └── destroy.py       # Destroy command guide
├── pyproject.toml           # Project configuration
├── README.md                # Documentation
└── LICENSE                  # MIT License

🤝 Contributing

Contributions are welcome! Here's how you can help:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes
Run tests and formatting
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with Rich for beautiful terminal output
Inspired by the need to make Infrastructure as Code more accessible to beginners
Thanks to the Terraform and OpenTofu communities

📞 Support

Issues

Report bugs

Discussions

Ask questions

Wiki

More docs

Made with ❤️ by CloudGrains for the Infrastructure as Code community

Star on GitHub

Overview

✨ Features

Core Features

🎯 Auto-Detection

📚 Interactive Guides

🎨 Beautiful TUI

⚡ No Setup Required

🛡️ Safety First

📖 Beginner-Friendly

Enterprise Features (v0.2.0) 🆕

🔍 Drift Detection

✅ Pre-Flight Validation

📦 State Explorer

📁 Workspace Manager

🚀 CI/CD Mode

📊 Resource Visualization

📋 Prerequisites

1. Python 3.8 or higher

2. Either Terraform OR OpenTofu (at least one required)

🚀 Installation

Option 1: Install with pipx (Recommended)

Option 2: Install from Source

Option 3: Install from PyPI (when published)

📖 Usage

Navigation

Example Workflow

Basic Workflow:

1. Initialize your project

2. Validate configuration

3. Preview changes

4. Apply changes

Advanced Workflow:

1. Check for drift

2. Explore state

3. Manage environments

4. Run CI/CD pipeline

🎯 Supported Commands

💡 Feature Deep Dive

🔍 Drift Detection

✅ Pre-Flight Validation

📦 State Explorer

📁 Workspace Manager

🚀 CI/CD Pipeline Mode

🔒 Security & Privacy

No Telemetry

No Network Calls

No Credentials Required

Open Source

Local Execution

🛠️ Development

Setting Up Development Environment

Running Tests

Code Formatting

Type Checking

📁 Project Structure

🗺️ Roadmap

Completed ✅

Coming Soon

🤝 Contributing

📄 License

🙏 Acknowledgments

📞 Support

Issues

Discussions

Wiki