tfmate

Documentation: https://tfmate.readthedocs.org

tfmate is a command line interface and Python library for analyzing Terraform configurations and state files. It provides powerful tools for understanding your infrastructure as code, including configuration analysis, AWS service discovery, and state file inspection.

Features

• Configuration Analysis: Analyze Terraform configuration files to understand providers, backends, and version constraints
• AWS Service Discovery: List and filter AWS services from botocore definitions
• State File Inspection: Extract Terraform version and metadata from state files
• Multiple Output Formats: Support for JSON, table, and text output formats
• Flexible Configuration: Customizable through configuration files and environment variables

Installation

tfmate supports Python 3.10+.

To install from PyPI:

pip install tfmate

To install using uv:

    sh -c "$(curl -fsSL https://astral.sh/uv/install)"
    uv tool install tfmate

Ensure you have ./local/bin in your PATH, since that's where uv puts the executable.

Quick Start

# Get help
tfmate --help

# Analyze Terraform configuration
tfmate analyze config

# List AWS services
tfmate aws services

# Get Terraform version from state
tfmate terraform version

# Recurse through all your .terraform folders and delete any unused provider or module code.
tfmate terraform prune-cache


# Use JSON output for scripting
tfmate --output json analyze config

Usage Examples

Analyze Terraform Configuration

# Analyze current directory
tfmate analyze config

# Analyze specific directory with detailed info
tfmate analyze config --directory ./infrastructure --show-providers --show-backend

# Output as JSON for scripting
tfmate --output json analyze config > config.json

AWS Service Discovery

# List all AWS services
tfmate aws services

# List only service names
tfmate aws services --names-only

# Filter services by pattern
tfmate aws services --filter-name "ec2*" --sort-by name

State File Operations

# Get Terraform version from state
tfmate terraform version

# Get version from specific directory
tfmate terraform version --directory ./infrastructure

# Use explicit state file (local only)
tfmate terraform version --state-file ./terraform.tfstate

Prune Stale Provider/Module Cache

# Recursively find .terraform cache directories and interactively prune stale
# provider versions and orphaned module checkouts left behind by
# `terraform init --upgrade`, comparing against .terraform.lock.hcl and
# modules.json
tfmate terraform prune-cache

# Preview what would be pruned without prompting or deleting anything
tfmate terraform prune-cache --dry-run

# Prune a specific directory tree
tfmate terraform prune-cache ./infrastructure

Documentation

For detailed documentation, visit: https://tfmate.readthedocs.org

• Installation Guide
• Quickstart Guide
• Usage Guide
• Configuration Guide
• Changelog

Development

To set up a development environment:

# Clone the repository
git clone https://github.com/caltechads/tfmate.git
cd tfmate

uv sync
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run tests
pytest

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

License

See LICENSE.txt in this project for the license.