infra-guide 0.2.0

An interactive TUI for Terraform and OpenTofu beginners with enterprise-grade features

infra-guide 🚀

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
• 🔄 Smart Validation: Syntax checking, format validation, and configuration analysis

🎬 Demo

🚀 infra-guide - Interactive Infrastructure Guide
📦 Using: terraform (v1.6.0)

┌──────────────────── Main Menu - Enhanced Edition ───────────────────┐
│ Option  Command      Description                                     │
│ 1       init         🔧 Initialize a working directory               │
│ 2       plan         📋 Show changes required                        │
│ 3       apply        ✅ Create or update infrastructure              │
│ 4       destroy      💥 Destroy infrastructure                       │
│ 5       validate     ✓ Run pre-flight validations                   │
│ 6       drift        🔍 Detect infrastructure drift                  │
│ 7       state        📦 Explore state file                           │
│ 8       workspace    📁 Manage workspaces                            │
│ 9       cicd         🚀 CI/CD pipeline mode                          │
│ 0       exit         🚪 Exit infra-guide                             │
└─────────────────────────────────────────────────────────┘

Select an option [1/2/3/4/5] (5):

📋 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

That's it! No cloud credentials, API keys, or additional setup needed.

🚀 Installation

Option 1: Install with pipx (Recommended)

pipx is the recommended way to install command-line tools in isolated environments. It's available for macOS, Linux, and Windows.

Install pipx:

• macOS: brew install pipx
• Linux (Ubuntu/Debian): sudo apt install pipx or pipx via package manager
• Windows: scoop install pipx or choco install pipx or download from PyPA

Install infra-guide:

pipx install infra-guide

Verify installation:

infra-guide --help

Option 2: Install from Source

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

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

# Install the package
pip install .

# Run the tool
infra-guide

Option 3: Install from GitHub (Development Version)

# Install directly from GitHub using pipx
pipx install git+https://github.com/iamtejas23/infra-guide.git

# Or from source directory
git clone https://github.com/iamtejas23/infra-guide.git
cd infra-guide
pip install -e .

📖 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)
2. Validate configuration - Select option 5 (validate) for pre-flight checks
3. Preview changes - Select option 2 (plan)
4. Apply changes - Select option 3 (apply)

Advanced Workflow:

1. Check for drift - Select option 6 (drift) to detect changes outside Terraform
2. Explore state - Select option 7 (state) to view current infrastructure
3. Manage environments - Select option 8 (workspace) to switch between dev/staging/prod
4. Run CI/CD pipeline - Select option 9 (cicd) for automated validation

🎯 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
• 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/iamtejas23/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                # This file
└── LICENSE                  # MIT License

🗺️ Roadmap

Completed ✅

• Core IaC commands (init, plan, apply, destroy)
• Drift detection
• Pre-flight validations
• State explorer with tree visualization
• Workspace management
• CI/CD pipeline mode
• Comprehensive error handling

Coming Soon

• Policy-as-code integration (OPA, Sentinel)
• Cost estimation before apply
• Graph visualization of resource dependencies
• Plan diff with syntax highlighting
• Custom command templates
• Configuration file for user preferences
• Color theme customization
• Command history and favorites
• Export reports to markdown/PDF
• Integration with popular CI/CD platforms
• Multi-language support
• Cloud provider-specific guidance
• Terraform/OpenTofu module browser

🤝 Contributing

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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests and formatting
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. 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: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: GitHub Wiki

⭐ Star History

If you find this project useful, please consider giving it a star on GitHub!

---

Made with ❤️ for the Infrastructure as Code community