cfn-cleanup

A lightweight CLI tool to automatically find and clean up stale AWS CloudFormation stacks that match a given prefix. Designed for teams that spin up ephemeral stacks for development, testing, or CI pipelines and need a safe, repeatable way to tear them down.

Use Case

CloudFormation stacks from feature branches, PR environments, and dev experiments accumulate quickly and silently inflate your AWS bill. cfn-cleanup gives you:

• A safe dry-run view of what would be deleted before you commit
• Age-based filtering so only truly stale stacks are targeted
• A protection tag to exclude stacks that must stay alive
• Parallel deletion with a configurable concurrency limit
• CI/CD-friendly --force mode to skip interactive prompts

Features

• List stacks filtered by name prefix (dry-run by default)
• Age filter — only target stacks older than N days
• Protection tag — stacks tagged cfn-cleanup:protected=true are never deleted
• Prefix length guard — requires at least 2 characters to prevent mass-deletion accidents
• Full AWS pagination support — won't miss stacks on large accounts
• Concurrent deletion with --concurrency
• AWS profile support via --profile
• CI-friendly --force flag to bypass confirmation

Installation

Using Go

go install github.com/thisguymartin/cfn-cleanup-go@latest

From Source

git clone https://github.com/thisguymartin/cfn-cleanup-go.git
cd cfn-cleanup-go
go build -o bin/cfn-cleanup .

# Optional: add to PATH
sudo mv bin/cfn-cleanup /usr/local/bin/

Usage

# List stacks matching a prefix (no deletion — safe to run anytime)
cfn-cleanup -prefix="my-team-dev"

# List stacks in a specific region
cfn-cleanup -prefix="my-team-dev" -region="us-west-2"

# List stacks older than 7 days
cfn-cleanup -prefix="my-team-dev" -max-age=7

# Preview what would be deleted (checks protection tags, no changes made)
cfn-cleanup -prefix="my-team-dev" -dry-run

# Preview with age filter
cfn-cleanup -prefix="my-team-dev" -max-age=7 -dry-run

# Delete matching stacks (interactive confirmation)
cfn-cleanup -prefix="my-team-dev" -region="us-west-2" -delete

# Delete stacks older than 14 days, skip confirmation (CI mode)
cfn-cleanup -prefix="my-team-dev" -max-age=14 -delete -force

# Delete using a specific AWS profile, 3 stacks at a time
cfn-cleanup -prefix="my-team-dev" -profile="staging" -delete -concurrency=3

Flags

Flag	Description	Default
-prefix	Stack name prefix to match (min 2 chars)	"thisguymartin-pit"
-region	AWS region	AWS_REGION env var or ~/.aws/config
-profile	AWS named profile	system default
-delete	Actually delete matching stacks	false
-dry-run	Preview what would be deleted (checks protection tags, no changes)	false
-force	Skip the y/N confirmation prompt	false
-max-age	Only target stacks older than N days (0 = all)	0
-concurrency	Number of stacks to delete in parallel	1

Guards & Safety

Minimum prefix length

The -prefix must be at least 2 characters. An empty or single-character prefix could match almost everything in an account, so the tool refuses to run.

Protected stacks

Tag any stack with cfn-cleanup:protected=true and cfn-cleanup will skip it automatically, even if it matches the prefix and age filter.

aws cloudformation update-stack \
  --stack-name my-important-stack \
  --use-previous-template \
  --tags Key=cfn-cleanup:protected,Value=true

Dry-run by default

Without -delete, the tool only lists matching stacks and exits. No changes are made.

Confirmation prompt

When -delete is used without -force, you must type y to confirm before any deletion starts.

AWS Credentials

Uses the standard AWS SDK credential chain:

1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN)
2. AWS credentials file (~/.aws/credentials)
3. AWS config file (~/.aws/config)
4. IAM instance profile / ECS task role (when running on AWS)

Documentation

• Use cases & examples — Feature branch cleanup, CI/CD, staging envs, cost optimization, and safety patterns.

Development

# Run tests
make test

# Verbose test output
make test-verbose

# Lint
make lint

# Build binary
make build