CF Purge

A powerful CLI tool for bulk-deleting AWS CloudFormation stacks using glob patterns. Perfect for cleaning up development environments, CI/CD temporary stacks, and feature branch deployments.

CF Purge is a powerful tool that PERMANENTLY DELETES AWS CloudFormation stacks and their resources.

• 🚨 Always test in non-production environments first
• 🔍 Understand the implications of deleting your infrastructure
• 💾 Have proper backups of critical data
• ✅ Use specific glob patterns to avoid accidental deletions
• 🎯 Review the list of matched stacks before confirming deletion

This tool will prompt you for confirmation before deleting any stacks, but deletion is irreversible.

This repository is structured as a monorepo:

• core/ — Go CLI app for bulk-deleting CloudFormation stacks
• website/ — Static website/landing page
• docs/ — Documentation assets

Before using CF Purge, ensure you have:

• ✅ AWS CLI configured with appropriate credentials
• ✅ IAM permissions for CloudFormation operations (see AWS Configuration)
• ✅ Go 1.22+ (only for building from source)
• ✅ Basic understanding of CloudFormation stacks
• ✅ Non-production environment for initial testing

brew tap dzhuneyt/tap
brew install cf-purge
cf-purge --version  # Verify installation

Download the latest binary for your platform from GitHub Releases.

Supported platforms:

• Linux (amd64, arm64, 386)
• macOS (amd64, arm64)
• Windows (amd64, 386)

git clone https://github.com/Dzhuneyt/cf-purge.git
cd cf-purge/core
go build -o cf-purge main.go

cf-purge --help

Create an IAM policy with the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "cloudformation:ListStacks",
                "cloudformation:DeleteStack",
                "cloudformation:DescribeStacks"
            ],
            "Resource": "*"
        }
    ]
}

Ensure AWS credentials are configured via one of these methods:

• AWS CLI: aws configure
• Environment variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY
• IAM roles (for EC2/Lambda execution)
• AWS profiles: export AWS_PROFILE=your-profile

Verify your configuration:

aws sts get-caller-identity

cf-purge --glob "PATTERN"

# Delete all development environment stacks
cf-purge --glob "*-dev"

# Delete all stacks ending with "-api"
cf-purge --glob "*-api"

# Delete all stacks starting with "my-stack-"
cf-purge --glob "my-stack-*"

# Delete stacks matching a specific pattern
cf-purge --glob "*-feature-branch-*"

cf-purge --glob "ci-build-*"
cf-purge --glob "*-pr-*"

cf-purge --glob "*-feature-user-auth-*"
cf-purge --glob "myapp-branch-*"

cf-purge --glob "*-dev"
cf-purge --glob "*-staging"
cf-purge --glob "test-*-tmp"

cf-purge --glob "*-sandbox-*"
cf-purge --glob "*-playground-*"

CF Purge will show you exactly which stacks match your pattern and ask for confirmation:

Glob pattern matched the following stacks:
----------------------------------------
my-app-dev-api
my-app-dev-database
my-app-dev-frontend
----------------------------------------
This operation will delete 3 stacks
THIS OPERATION IS DESTRUCTIVE AND IRREVERSIBLE
Please, confirm that you want to delete these stacks irreversibly.
[y/N]: 

Type y and press Enter to proceed, or any other key to cancel.

• Cause: Insufficient IAM permissions
• Solution: Ensure your AWS credentials have the required CloudFormation permissions (see AWS Configuration)

• Cause: Stack resources have dependencies, deletion protection, or retain policies
• Solution:
  • Check stack events in the AWS Console for specific resource errors
  • Manually resolve resource dependencies
  • Disable deletion protection on protected resources

• Cause: Glob pattern doesn't match any existing stack names
• Solution:
  • List all stacks: aws cloudformation list-stacks
  • Test your pattern with a broader glob first
  • Check for typos in the pattern

• 📖 Check Issues for similar problems
• 📚 Review AWS CloudFormation documentation for stack deletion limitations
• 💬 Use cf-purge --help for command options
• 🐛 Report bugs or request features via GitHub Issues

• ⚡ Processes stacks sequentially to avoid AWS API throttling
• 🕐 Large numbers of stacks may take several minutes to delete
• 🔒 No parallel deletion to ensure safe operation and proper confirmation (parallel deletion with configurable concurrency is planned for future releases)

• ❌ Stack deletion failures require manual intervention (see roadmap)
• ❌ No progress indicator for long-running operations
• ❌ No dry-run mode (planned feature)

• 🎯 Use specific patterns to avoid accidental deletions
• 🧪 Test patterns in development environments first
• 📦 Delete in smaller batches for large numbers of stacks
• 📋 Keep a record of important stacks before bulk operations

• ✅ Delete by prefix or suffix, not just by glob pattern
• ✅ CI to auto-publish to HomeBrew for easier installation and usage

• Dry-run mode - Preview which stacks would be deleted without actually deleting them
• Handle delete failures due to stack dependencies with automatic retries
• Progress indicators for long-running operations

• Parallel deletion with configurable concurrency
• Stack filtering by tags, creation date, or status

• Regex pattern support in addition to glob patterns

We welcome contributions! Here's how you can help:

git clone https://github.com/Dzhuneyt/cf-purge.git
cd cf-purge/core
go mod download
go run main.go --help

• 🐛 Report bugs or request features via Issues
• 📖 Improve documentation
• 🧪 Add test cases
• ⚡ Implement features from the roadmap
• 🎨 Enhance the website

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes in the core/ directory
4. Test thoroughly with non-production stacks
5. Commit your changes: git commit -m "Add your feature"
6. Push to your fork: git push origin feature/your-feature-name
7. Submit a pull request with a clear description

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

• 📧 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 📖 Documentation: This README and GitHub Wiki

Remember: With great power comes great responsibility. Use CF Purge wisely! 🚀