s3-bucket-delete

A command-line tool to safely delete AWS S3 buckets and all their contents by matching a substring pattern.

⚠️ WARNING

This tool will permanently delete S3 buckets and all their contents. This action cannot be undone. Use with extreme caution and ensure you have proper backups before running this tool.

Features

• 🔍 Pattern Matching: Find buckets by substring pattern
• 🛡️ Safety Checks: Confirms before deletion and validates AWS credentials
• 🗑️ Complete Cleanup: Removes all objects, versions, and delete markers
• 📋 Clear Output: Shows exactly what will be deleted before proceeding
• ✅ Error Handling: Gracefully handles permission errors and missing buckets

Installation

Global Installation (Recommended)

npm install -g s3-bucket-delete

Local Installation

npm install s3-bucket-delete

Prerequisites

1. AWS CLI: Must be installed and configured

   • Installation Guide
   • Configure with aws configure or environment variables

2. AWS Permissions: Your AWS credentials must have the following permissions:

   • s3:ListBucket
   • s3:DeleteObject
   • s3:DeleteObjectVersion
   • s3:DeleteBucket
   • s3:ListAllMyBuckets

Usage

s3-bucket-delete <bucket-name-substring>

Examples

# Delete all buckets containing "test"
s3-bucket-delete test

# Delete all buckets containing "staging-app"
s3-bucket-delete staging-app

# Delete all buckets containing "temp-2024"
s3-bucket-delete temp-2024

How It Works

1. Search: Finds all S3 buckets containing the specified substring
2. Display: Shows all matching buckets that will be deleted
3. Confirm: Asks for explicit confirmation before proceeding
4. Clean: Removes all objects, versions, and delete markers from each bucket
5. Delete: Removes the empty buckets

Safety Features

• Dry Run Display: Shows exactly which buckets will be deleted before taking action
• Explicit Confirmation: Requires manual confirmation (y/Y) to proceed
• AWS Validation: Checks for AWS CLI installation and valid credentials
• Error Handling: Continues with other buckets if one fails
• Detailed Logging: Shows progress and results for each operation

What Gets Deleted

This tool performs a complete cleanup of matching buckets:

• ✅ All objects (files and folders)
• ✅ All object versions (if versioning is enabled)
• ✅ All delete markers
• ✅ The bucket itself

Example Output

$ s3-bucket-delete test

Searching for buckets matching: 'test'...

⚠️  WARNING: The following buckets match the pattern and will be PERMANENTLY deleted:
==================================================
  • my-test-bucket-1
  • test-application-logs
  • user-test-data
==================================================

This action will:
1. Delete ALL files and folders in each bucket
2. Delete the bucket itself
3. This action CANNOT be undone!

Are you sure you want to EMPTY and DELETE these buckets? (y/N): y

🗑️  Emptying bucket: my-test-bucket-1
   Removing all objects...
   Removing all object versions...
   Removing delete markers...
🗑️  Deleting bucket: my-test-bucket-1
✅ Successfully deleted bucket: my-test-bucket-1

✅ Operation completed.

Error Handling

The tool handles common error scenarios:

• AWS CLI not installed: Provides installation instructions
• Invalid credentials: Prompts to configure AWS credentials
• Permission errors: Continues with other buckets
• Non-existent buckets: Skips and continues with others

Best Practices

1. Test First: Run with a unique test bucket name to verify behavior
2. Check Permissions: Ensure you have the necessary AWS permissions
3. Backup Important Data: Always backup critical data before deletion
4. Use Specific Patterns: Use specific substring patterns to avoid accidental deletions
5. Review the List: Always carefully review the list of buckets before confirming

Troubleshooting

"AWS CLI is not installed"

Install the AWS CLI following the official guide.

"AWS credentials not configured"

Configure your credentials using:

aws configure

"No buckets found matching"

• Verify your substring pattern is correct
• Check that you have permission to list buckets
• Ensure you're in the correct AWS region/account

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

If you encounter issues or have questions:

• Check the troubleshooting section above
• Review AWS CLI documentation
• Create an issue on GitHub

Remember: This tool permanently deletes data. Always double-check what you're deleting!