Skip to main content

Getting Started

Get up and running with tf2report in 5 minutes!

Prerequisites​

Before you start, ensure you have:

  • Terraform installed (any recent version)
  • Go 1.25+ (if building from source)
  • A Terraform configuration ready to plan

Installation​

Choose your preferred installation method:

The easiest way to install tf2report:

go install github.com/germainlefebvre4/tf2report/cmd/tf2report@latest

Verify the installation:

tf2report --help

From Source​

Build from the latest source code:

# Clone the repository
git clone https://github.com/germainlefebvre4/tf2report.git
cd tf2report

# Build the binary
make build

# Install to /usr/local/bin (requires sudo)
sudo make install

Docker (Coming Soon)​

docker pull germainlefebvre4/tf2report:latest

Your First Report​

Let's generate your first Terraform plan report!

Step 1: Create a Terraform Plan​

Navigate to your Terraform project and create a plan:

cd /path/to/your/terraform/project
terraform plan -out=tfplan

Step 2: Convert Plan to JSON​

Terraform's JSON output is what tf2report analyzes:

terraform show -json tfplan > terraform.tfplan.json

Step 3: Generate a Report​

Now run tf2report:

tf2report --plan terraform.tfplan.json

🎉 Congratulations! You've generated your first report.

Understanding the Output​

The default Markdown output includes:

  1. Header - Terraform version information
  2. Summary - Total changes and counts by action type
  3. Changes by Resource Type - Detailed breakdown of each resource

Example output:

# Terraform Plan Summary

**Terraform Version:** 1.10.5

## Summary

**Total Changes:** 3

| Action | Count |
|--------|-------|
| Add | 2 |
| Change | 1 |

## Changes by Resource Type

### aws_s3_bucket (2)

**To Add (2):**
- `aws_s3_bucket.data`
- `aws_s3_bucket.logs`

### aws_instance (1)

**To Change (1):**
- `aws_instance.web[0]`

Try Different Formats​

Plain Text​

Great for terminal viewing:

tf2report --plan terraform.tfplan.json --format text

JSON​

Perfect for automation and scripts:

tf2report --plan terraform.tfplan.json --format json

Save Output to a File​

Redirect output to save your report:

# Markdown
tf2report --plan terraform.tfplan.json > report.md

# JSON
tf2report --plan terraform.tfplan.json --format json > report.json

Filter Changes​

Focus on specific resources or actions:

# Only show S3 bucket changes
tf2report --plan terraform.tfplan.json --type aws_s3_bucket

# Only show resources being created
tf2report --plan terraform.tfplan.json --action create

# Combine filters
tf2report --plan terraform.tfplan.json --type aws_s3_bucket --action create

Use a Configuration File​

For repeated use, create a configuration file:

tf2report.yaml
terraform_plan_path: terraform.tfplan.json
output_format: markdown
filters:
  resource_types:
    - aws_instance
    - aws_s3_bucket
  actions:
    - create
    - delete
verbosity: info

Then simply run:

tf2report

Next Steps​

Now that you've generated your first report, explore more features:

Troubleshooting​

Command not found​

If tf2report is not found after installation:

  1. Check your $GOPATH/bin is in your $PATH:

    echo $PATH | grep -q "$GOPATH/bin" || echo "Add $GOPATH/bin to PATH"

  2. Add to your shell profile (.bashrc, .zshrc, etc.):

    export PATH="$PATH:$(go env GOPATH)/bin"

Invalid JSON format​

Make sure you're using the JSON output from terraform show -json, not the plan file directly.

Need Help?​