tfvm

Terraform Version Manager (TFVM)

A modern, fast CLI tool to manage multiple Terraform versions on your system

Never worry about Terraform version conflicts again! 🚀
Seamlessly switch between Terraform versions for different projects, just like nvm for Node.js.

🎯 Why TFVM?

• 🏢 Multiple Projects? Different projects often require different Terraform versions
• 🔄 Legacy Support? Need to maintain older infrastructure with specific Terraform versions
• 🆕 Latest Features? Want to try new Terraform features without breaking existing workflows
• 👥 Team Consistency? Ensure your entire team uses the same Terraform version
• 🛡️ Risk Mitigation? Test upgrades safely before applying to production

TFVM solves all of this with simple, intuitive commands.

✨ What's New in v2.0

• ⚡ Faster & Lighter - Reduced bundle size to ~9KB (98% smaller!)
• 🔄 Auto-Update Check - Get notified when new versions are available
• 🌐 Modern APIs - Built with Fetch API for Node.js 18+ compatibility
• 🧪 Better Testing - Comprehensive test suite with Bun test runner
• 📦 Fewer Dependencies - Streamlined to essential packages only
• 🚀 Improved Performance - Optimized async operations throughout

🚀 Quick Start

Requirements: Node.js >= 18.0.0

Install globally via npm:

npm install -g tfvm

Or with other package managers:

# Using yarn
yarn global add tfvm

# Using pnpm  
pnpm add -g tfvm

# Using bun
bun add -g tfvm

🎬 Quick Demo

# 1. Install a specific Terraform version
$ tfvm download 1.6.0

# 2. Switch to it  
$ tfvm use

# 3. Verify it's active
$ terraform version
Terraform v1.6.0

# 4. List all your versions
$ tfvm list

✨ Features

• 🔄 Easy version switching - Switch between Terraform versions with one command
• 📦 Automatic downloads - Download any Terraform version from HashiCorp's official releases
• 🎯 Interactive prompts - User-friendly selection menus and confirmations
• 🗂️ Local management - Keep multiple versions locally and switch as needed
• 🖥️ Cross-platform - Works on Windows, macOS, and Linux
• ⚡ Fast & lightweight - Optimized bundle size (~9KB) with minimal dependencies
• 🔧 Configurable - Customize storage directory via configuration files
• 🛡️ Safe operations - Confirmation prompts for destructive actions
• 🔍 Version discovery - Browse all available Terraform releases
• 📊 Smart filtering - Automatically handles platform-specific downloads
• 🔔 Update notifications - Get notified when new TFVM versions are available

🚀 Common Use Cases

🏗️ Project-specific Terraform versions

# For legacy project requiring Terraform 1.4.x
cd legacy-infrastructure
tfvm use  # Select 1.4.6

# For new project using latest features  
cd new-infrastructure
tfvm use  # Select 1.6.0

🔬 Testing Terraform upgrades

# Download the new version
tfvm download 1.6.0

# Test with new version
tfvm use  # Select 1.6.0
terraform plan

# Rollback if issues found
tfvm use  # Select your stable version

👥 Team synchronization

# Team lead shares the version
echo "Team is using Terraform 1.5.7"

# Everyone downloads the same version
tfvm download 1.5.7
tfvm use  # Select 1.5.7

# Verify consistency
terraform version

📋 Available Commands

tfvm list | tfvm ls

List locally downloaded Terraform versions or browse remote versions.

Local versions:

tfvm list    # Show all locally installed versions
tfvm ls      # Short alias

Remote versions:

tfvm list --remote    # Browse all available versions from HashiCorp
tfvm ls -r           # Short alias with flag

No versions installed:

tfvm download | tfvm d

Download and install Terraform versions from HashiCorp's official releases.

Interactive download:

tfvm download    # Browse and select from all available versions
tfvm d          # Short alias

Version-specific download:

tfvm download 1.6.0    # Download specific version releases
tfvm d 1.6.0          # Short alias

tfvm remove | tfvm rm

Remove installed Terraform versions from your system.

Remove specific version:

tfvm remove    # Select which version to remove
tfvm rm       # Short alias

Remove all versions:

tfvm remove --all    # Remove all installed versions
tfvm rm -a          # Short alias with flag

tfvm use

Set a specific Terraform version as the default system version.

tfvm use    # Select from installed versions to set as default

💡 Note: You may need to add the TFVM directory to your PATH environment variable. The tfvm dir command shows the exact path to add.

tfvm dir

Display the directory where Terraform executables are stored.

tfvm dir    # Shows storage directory (default: ~/.tfvm)

🔧 Configuration

TFVM can be configured using RC files. Create a .tfvmrc file in your home directory:

{
  "TERRAFORM_RELEASE_REPO": "https://releases.hashicorp.com/terraform",
  "STORAGE_DIR": "/custom/path/to/terraform/versions",
  "TFVM_PATH": "/custom/path/to/terraform/versions"
}

Environment Variables

You can also use environment variables for configuration:

export TFVM_STORAGE_DIR="/opt/terraform-versions"
export TFVM_PATH="/opt/terraform-versions"

Advanced Configuration

Custom Release Repository

{
  "TERRAFORM_RELEASE_REPO": "https://your-custom-mirror.com/terraform"
}

Corporate Environment Setup

# Set custom paths for corporate environments
export TFVM_STORAGE_DIR="/shared/tools/terraform"
export TFVM_PATH="/shared/tools/terraform"

# Or create a system-wide config
sudo mkdir -p /etc/tfvm
echo '{"STORAGE_DIR": "/shared/tools/terraform"}' | sudo tee /etc/tfvm/config.json

🛠️ Development

This project is built with modern tools for optimal performance:

• Runtime - Node.js 18+ (for production) / Bun (for development)
• TypeScript - Type-safe development with ESNext features
• Bun - Fast bundling and testing
• Modern APIs - Fetch API for HTTP requests (Node.js 18+)
• Modern Dependencies:
  • citty - Modern lightweight CLI framework
  • @clack/prompts - Beautiful interactive prompts
  • node-html-parser - Fast HTML parsing
  • fflate - Fast ZIP compression
  • picocolors - Ultra-lightweight terminal colors (~1KB)

Building from source

# Clone the repository
git clone https://github.com/anindya-dey/tfvm.git
cd tfvm

# Install dependencies with Bun (recommended)
bun install

# Or use npm/pnpm/yarn
npm install

# Build the project (creates Node.js-compatible bundle)
bun run build

# Run tests
bun test

# Run tests with coverage
bun run test:coverage

# Type check
bun run lint

# Link for local development
npm link

Tech Stack Details

Development:

• Built with Bun for fast development experience
• TypeScript with strict mode enabled
• ES modules in source code
• Comprehensive test suite using Bun's test runner
• CI/CD with GitHub Actions testing Node.js 18, 20, and 22

Production:

• Bundled to CommonJS for broad Node.js compatibility
• Minified output (~11KB)
• Node.js 18+ required (uses native Fetch API)
• Zero TypeScript runtime dependencies
• Modern, lightweight dependencies

📁 Storage Structure

TFVM organizes Terraform versions in your home directory:

~/.tfvm/
├── terraform_1.5.0      # Terraform v1.5.0 executable
├── terraform_1.6.0      # Terraform v1.6.0 executable  
├── terraform_1.7.0      # Terraform v1.7.0 executable
├── terraform            # Symlink to currently active version
└── .version-check       # Update check cache (auto-managed)

🔍 Troubleshooting

❓ Command not found after installation

Problem: tfvm: command not found

Solutions:

• Ensure ~/.tfvm is in your PATH environment variable
• Run tfvm dir to see the exact path to add
• Restart your terminal/shell
• For global npm installs, check npm config get prefix

# Add to your shell profile (.bashrc, .zshrc, etc.)
export PATH="$HOME/.tfvm:$PATH"

🌐 Network issues during download

Problem: Downloads fail or timeout

Solutions:

• Check internet connectivity
• Verify access to https://releases.hashicorp.com
• Check if you're behind a corporate firewall
• Try using a VPN or different network

# Test connectivity
curl -I https://releases.hashicorp.com/terraform/

🔐 Permission errors

Problem: Permission denied errors

Solutions:

• Ensure write permissions to home directory
• On Unix systems, make executables executable
• Check file ownership
• Avoid using sudo with tfvm

# Fix permissions on Unix systems
chmod +x ~/.tfvm/terraform_*
chown -R $USER:$USER ~/.tfvm/

🔄 Terraform version not switching

Problem: terraform version shows wrong version after tfvm use

Solutions:

• Check if PATH includes TFVM directory first
• Restart terminal session
• Verify no other Terraform installations override
• Check for shell aliases

# Debug PATH order
echo $PATH | tr ':' '\n' | grep -E "(tfvm|terraform)"

# Check which terraform binary is being used
which terraform

🗂️ Storage directory issues

Problem: Can't find downloaded versions

Solutions:

• Run tfvm dir to see current storage location
• Check if custom config is overriding default path
• Verify directory permissions

# Check storage directory
tfvm dir
ls -la $(tfvm dir)

🤝 Contributing

We welcome contributions! TFVM is open source and community-driven.

Quick Contribution Guide

• 🍴 Fork the repository
• 🌿 Create your feature branch (git checkout -b feature/amazing-feature)
• ✨ Make your changes with tests
• ✅ Test your changes (bun test)
• 📝 Commit your changes (git commit -m 'Add amazing feature')
• 🚀 Push to the branch (git push origin feature/amazing-feature)
• 📬 Open a Pull Request

📚 Documentation

For detailed guides on contributing and releasing:

• Versioning Guide - Semantic versioning conventions and commit message format
• Tagging & Release Guide - How to create releases and publish to npm

Development Setup

# Clone and setup
git clone https://github.com/anindya-dey/tfvm.git
cd tfvm
bun install

# Make changes and test
bun run build
bun test

# Check types
bun run lint

# Link for local testing
npm link

# Test the CLI locally
tfvm --version

🐛 Bug Reports

Found a bug? Please open an issue with:

• Environment details (OS, Node.js version, etc.)
• Steps to reproduce the issue
• Expected vs actual behavior
• Screenshots or terminal output if applicable

💡 Feature Requests

Have an idea? We'd love to hear it! Open an issue describing:

• The problem you're trying to solve
• Your proposed solution
• Alternative solutions you've considered
• Use cases and examples

🎯 Areas We Need Help

• 🧪 Testing - More test coverage and edge cases
• 📖 Documentation - Improve guides and examples
• 🌍 Internationalization - Support for other languages
• 🚀 Performance - Optimization and speed improvements
• 🔧 Features - New functionality and enhancements

📄 License

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

🙏 Acknowledgments

• Inspiration: nvm for Node.js version management
• Documentation: GIFs created using terminalizer
• Built with: Bun for blazing-fast development
• Creator: Built with ❤️ by Anindya Dey
• Community: Thanks to all contributors and users!

📈 Project Stats

• 🎯 Bundle Size: ~11KB (minified)
• 🧪 Test Coverage: 28 passing tests
• 📦 Dependencies: 5 runtime, 3 dev
• 🚀 Performance: Built with modern Fetch API
• ⚡ Development: Powered by Bun
• 🔄 CI/CD: Automated testing on Node.js 18, 20, 22

⭐ If TFVM helps you, please consider giving it a star on GitHub! ⭐

Made with TypeScript & Bun • Powered by Open Source • Built for Developers

Report Bug · Request Feature · Contribute