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

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

• Terraform: Download and Install
• OpenTofu: Download and Install

🚀 Installation

sudo apt update
sudo apt install pipx

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

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

# Install the package
pip install .

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

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

📖 Usage

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

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

💡 Feature Deep Dive

🔒 Security & Privacy

🛠️ Development

Setting Up Development Environment

# Clone the repository
git clone https://github.com/cloudgrains/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

Code Formatting

Type Checking

📁 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

🗺️ Roadmap

Completed ✅

Coming Soon

🤝 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