{"id":14154983,"url":"https://github.com/go-to-k/delstack","last_synced_at":"2026-04-02T19:04:46.465Z","repository":{"id":57133520,"uuid":"505099309","full_name":"go-to-k/delstack","owner":"go-to-k","description":"The CLI tool to force delete the entire AWS CloudFormation stack, even if it contains resources that fail to delete by the CloudFormation delete operation.","archived":false,"fork":false,"pushed_at":"2024-04-23T15:41:06.000Z","size":571,"stargazers_count":37,"open_issues_count":10,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-07-18T10:11:48.012Z","etag":null,"topics":["aws","aws-cdk","aws-cloudformation","aws-sam","cli","cloudformation","go","golang","serverless-framework"],"latest_commit_sha":null,"homepage":"https://dev.to/aws-builders/a-cli-tool-to-force-delete-cloudformation-stacks-3808","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/go-to-k.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-19T12:10:29.000Z","updated_at":"2024-08-08T07:23:24.303Z","dependencies_parsed_at":"2022-08-26T12:21:16.915Z","dependency_job_id":"52a0ec22-9028-4c8b-9861-6f4485864968","html_url":"https://github.com/go-to-k/delstack","commit_stats":{"total_commits":304,"total_committers":3,"mean_commits":"101.33333333333333","dds":0.08552631578947367,"last_synced_commit":"78cd91e12e3eca7bd2ad81c06f584e73fd0e05c3"},"previous_names":[],"tags_count":48,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-to-k%2Fdelstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-to-k%2Fdelstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-to-k%2Fdelstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/go-to-k%2Fdelstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/go-to-k","download_url":"https://codeload.github.com/go-to-k/delstack/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":215735785,"owners_count":15923388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-cdk","aws-cloudformation","aws-sam","cli","cloudformation","go","golang","serverless-framework"],"created_at":"2024-08-17T08:01:40.388Z","updated_at":"2026-04-02T19:04:46.449Z","avatar_url":"https://github.com/go-to-k.png","language":"Go","funding_links":[],"categories":["cli"],"sub_categories":[],"readme":"# delstack\n\n[![Go Report Card](https://goreportcard.com/badge/github.com/go-to-k/delstack)](https://goreportcard.com/report/github.com/go-to-k/delstack) ![GitHub](https://img.shields.io/github/license/go-to-k/delstack) ![GitHub](https://img.shields.io/github/v/release/go-to-k/delstack) [![ci](https://github.com/go-to-k/delstack/actions/workflows/ci.yml/badge.svg)](https://github.com/go-to-k/delstack/actions/workflows/ci.yml)\n\n## What is\n\nA CLI tool for deleting AWS CloudFormation stacks. Handles everything from routine deletions to stacks containing resources that fail to delete. Unlike CloudFormation's built-in `FORCE_DELETE_STACK` which leaves failed resources behind, **delstack** actually cleans them up with **no orphaned resources**.\n\nWorks with stacks from **AWS CDK**, **AWS SAM**, **AWS Amplify**, **Serverless Framework**, and any IaC tool using CloudFormation.\n\n![delstack](https://github.com/user-attachments/assets/4f02526d-536c-4a23-81fd-10484902133f)\n\nFor CDK apps, `delstack cdk` synthesizes, discovers all stacks (including cross-region), and deletes them with dependency resolution:\n\n![delstack for CDK](https://github.com/user-attachments/assets/0222969c-8c19-4700-80ce-096654ffba74)\n\n## Features\n\n- **Force delete undeletable resources**: Automatically cleans up resources blocking deletion, such as non-empty S3 buckets, and [more resource types](#resource-types-that-can-be-forced-to-delete)\n- **Parallel deletion with dependency resolution**: Deletes multiple stacks with maximum parallelism while respecting inter-stack dependencies\n- **Interactive stack selection**: Search and select stacks in a TUI with case-insensitive filtering\n- **Deletion protection handling**: Detects resource-level protection (EC2, RDS, Cognito, etc.) and stack TerminationProtection. With `-f`, automatically disables them before deletion\n- **Pre-deletion optimization**: Detaches Lambda VPC configurations in parallel to eliminate ENI cleanup wait time\n- **Retain policy override**: Force deletes resources with `Retain` or `RetainExceptOnCreate` deletion policies via `-f`\n- **GitHub Actions support**: Available as a [GitHub Actions](#github-actions) workflow for CI/CD stack cleanup\n- **[CDK integration](#cdk-integration)**: Run `delstack cdk` in a CDK app directory to synthesize, discover all stacks (including cross-region), and delete them with dependency resolution\n\n## Install\n\n- Homebrew\n\n  ```bash\n  brew install go-to-k/tap/delstack\n  ```\n\n- Linux, Darwin (macOS) and Windows\n\n  ```bash\n  curl -fsSL https://raw.githubusercontent.com/go-to-k/delstack/main/install.sh | sh\n  delstack -h\n\n  # To install a specific version of delstack\n  # e.g. version 1.2.0\n  curl -fsSL https://raw.githubusercontent.com/go-to-k/delstack/main/install.sh | sh -s \"v1.2.0\"\n  delstack -h\n  ```\n\n- aqua\n\n  ```bash\n  aqua g -i go-to-k/delstack\n  ```\n\n- Binary\n  - [Releases](https://github.com/go-to-k/delstack/releases)\n- Git Clone and install (for developers)\n\n  ```bash\n  git clone https://github.com/go-to-k/delstack.git\n  cd delstack\n  make install\n  ```\n\n## How to use\n\n  ```bash\n  delstack [-s \u003cstackName\u003e] [-p \u003cprofile\u003e] [-r \u003cregion\u003e] [-i|--interactive] [-f|--force] [-y|--yes] [-n \u003cconcurrencyNumber\u003e]\n  ```\n\n- -s, --stackName: optional\n  - CloudFormation stack name\n    - Required in non-interactive mode\n    - In interactive mode, you can select stacks from the UI instead\n  - **Multiple stack names can be specified.**\n    - `delstack -s test1 -s test2`\n    - **Multiple stacks are deleted in parallel by default, taking dependencies between stacks into account.**\n    - You can limit the number of parallel deletions with the `-n` option (e.g., `delstack -s test1 -s test2 -s test3 -n 2`).\n- -p, --profile: optional\n  - AWS profile name\n- -r, --region: optional(default: `us-east-1`)\n  - AWS Region\n- -i, --interactive: optional\n  - Interactive Mode\n- -f, --force: optional\n  - Force Mode to delete stacks including resources with **deletion policy `Retain`/`RetainExceptOnCreate`**, resources with **deletion protection**, and stacks with **TerminationProtection**\n- -y, --yes: optional\n  - Skip confirmation prompts (e.g., TerminationProtection disable confirmation)\n- -n, --concurrencyNumber: optional(default: unlimited)\n  - Specify the number of parallel stack deletions. Default is unlimited (delete all stacks in parallel).\n\n### CDK Integration\n\n  ```bash\n  delstack cdk [-s \u003cstackName\u003e] [-a \u003ccdkOutPath\u003e] [-c \u003ckey=value\u003e] [-p \u003cprofile\u003e] [-i] [-f] [-y] [-n \u003cconcurrencyNumber\u003e]\n  ```\n\n- -a, --app: optional\n  - Path to an existing `cdk.out` directory. When specified, `npx cdk synth` is skipped and the manifest is read directly.\n- -c, --context: optional (repeatable)\n  - CDK context values in `key=value` format, passed to `npx cdk synth -c key=value`.\n- All global options (`-s`, `-p`, `-r`, `-i`, `-f`, `-y`, `-n`) also work with the `cdk` subcommand.\n- **Requires**: [AWS CDK CLI](https://docs.aws.amazon.com/cdk/v2/guide/cli.html) installed (unless using `-a`).\n\n  ```bash\n  delstack cdk                         # Synthesize and delete all stacks\n  delstack cdk -c env=dev              # With CDK context\n  delstack cdk -a ./cdk.out            # Use existing cdk.out (skip synthesis)\n  delstack cdk -s MyStack              # Delete specific stack\n  delstack cdk -i                      # Interactive selection\n  delstack cdk -f -y                   # Force delete, skip confirmation\n  ```\n\nFor details on cross-region deletion, see [CDK Integration Details](#cdk-integration-details).\n\n## Resource Types that can be forced to delete\n\nThis tool supports force deletion of the following resource types that cause `DELETE_FAILED` in normal CloudFormation stack deletion. All other resources are deleted normally, so you can use this tool for any stack.\n\nIf you need support for additional resource types, please create an issue at [GitHub](https://github.com/go-to-k/delstack/issues).\n\n|  RESOURCE TYPE  |  DETAILS  |\n| ---- | ---- |\n|  AWS::S3::Bucket  |  S3 Buckets, including **non-empty buckets or buckets with Versioning enabled**.  |\n|  AWS::S3Express::DirectoryBucket  |  S3 Directory Buckets for S3 Express One Zone, including non-empty buckets.  |\n|  AWS::S3Tables::TableBucket  |  S3 Table Buckets, including buckets with any namespaces or tables.  |\n|  AWS::S3Tables::Namespace  |  S3 Table Namespaces, including namespaces with any tables.  |\n|  AWS::S3Vectors::VectorBucket  |  S3 Vector Buckets, including buckets with any indexes.  |\n|  AWS::IAM::Group  |  IAM Groups, including groups **with IAM users from outside the stack.** In that case, this tool detaches the IAM users and then deletes the IAM group (but not the IAM users themselves).  |\n|  AWS::ECR::Repository  |  ECR Repositories, including repositories that contain images and where **the `EmptyOnDelete` is not true.**  |\n|  AWS::Backup::BackupVault  |  Backup Vaults, including vaults **containing recovery points**.  |\n|  AWS::Athena::WorkGroup  |  Athena WorkGroups, including workgroups containing **named queries or prepared statements**.  |\n|  AWS::Lambda::Function  |  Lambda Functions, including **Lambda@Edge functions with replicas** still being cleaned up by AWS. Waits for AWS to finish removing edge replicas.  |\n|  AWS::CloudFormation::Stack  |  **Nested Child Stacks** that failed to delete. If any of the other resources are included in the child stack, **they too will be deleted**.  |\n|  AWS::CloudFormation::CustomResource  |  Custom Resources (AWS::CloudFormation::CustomResource), including resources that **do not return a SUCCESS status.**  |\n|  Custom::Xxx  |  Custom Resources (Custom::Xxx), including resources that **do not return a SUCCESS status.**  |\n\n\u003e **Note**: If there are resources other than those listed above that result in DELETE_FAILED, the deletion will fail. Resources that are **referenced by stacks outside the deletion targets** are not supported for force deletion. However, if all dependent stacks are included in the deletion targets, they are [deleted in the correct dependency order automatically](#parallel-stack-deletion-with-automatic-dependency-resolution).\n\n## Pre-deletion Processing\n\nThis tool automatically performs the following processing **before CloudFormation deletion starts**.\n\n### Deletion Protection Check\n\nChecks for resource-level deletion protection before attempting stack deletion.\n\n**Without `-f` option**: If any resources have deletion protection enabled, the tool reports them and aborts without attempting deletion.\n\n**With `-f` option**: Deletion protection is automatically disabled before deletion proceeds.\n\n|  RESOURCE TYPE  |\n| ---- |\n|  AWS::EC2::Instance  |\n|  AWS::RDS::DBInstance  |\n|  AWS::RDS::DBCluster  |\n|  AWS::Cognito::UserPool  |\n|  AWS::Logs::LogGroup  |\n|  AWS::ElasticLoadBalancingV2::LoadBalancer  |\n\n### Performance Optimization\n\nThe following resources do not fail during normal deletion, but are optimized in advance to improve deletion speed.\n\n|  RESOURCE TYPE  |  DETAILS  |\n| ---- | ---- |\n|  AWS::Lambda::Function  |  Automatically detaches VPC configurations from Lambda functions and deletes their ENIs in parallel, **eliminating ENI cleanup wait time**. All Lambda functions within a stack (including nested stacks) are processed in parallel for maximum performance.  |\n\n## Interactive Mode\n\n### Stack Name Selection\n\nWhen using interactive mode (`-i, --interactive`) without specifying stack names, you can search stack names **case-insensitively** and select stacks.\n\nThe filter keyword can be **empty**.\n\n```bash\n❯ delstack -i\nFilter a keyword of stack names(case-insensitive): goto\n```\n\nThen you select stack names in the UI.\n\n```bash\n? Select StackNames.\nNested child stacks, XXX_IN_PROGRESS(e.g. ROLLBACK_IN_PROGRESS) status stacks and EnableTerminationProtection stacks are not displayed.\n  [Use arrows to move, space to select, \u003cright\u003e to all, \u003cleft\u003e to none, type to filter]\n  [x]  dev-goto-04-TestStack\n  [ ]  dev-GOTO-03-TestStack\n\u003e [x]  dev-Goto-02-TestStack\n  [ ]  dev-goto-01-TestStack\n```\n\n### Stacks excluded from interactive selection\n\n- **Nested child stacks**: Parent stacks should generally be deleted as a whole. If you need to delete a child stack directly, specify its name with the `-s` option instead of using interactive mode.\n- **`XXX_IN_PROGRESS` stacks** (e.g. `ROLLBACK_IN_PROGRESS`): Multiple CloudFormation operations should not run on the same stack simultaneously.\n- **TerminationProtection stacks**: Not displayed without `-f`. With `-f`, they appear with a **`*` prefix marker**.\n\n## Force Mode\n\nThe `-f, --force` option enables deletion of stacks that would otherwise be blocked:\n\n- **Retain/RetainExceptOnCreate deletion policies**: Resources with these policies are force deleted instead of being retained\n- **Resource-level deletion protection** (EC2, RDS, Cognito, etc.): Protection is automatically disabled before deletion\n- **Stack TerminationProtection**: After a confirmation prompt, protection is disabled and the stack is deleted\n\n```bash\ndelstack -f -s dev-goto-01-TestStack\n```\n\n### Large Template Handling\n\nWhen using force mode with stacks that have large templates (exceeding **51,200 bytes**, CloudFormation's direct template size limit), `delstack` automatically:\n\n1. Creates a temporary S3 bucket in your account\n2. Uploads the modified template to the bucket\n3. Updates the stack via S3 template URL\n4. Deletes the temporary S3 bucket after the operation completes\n\n## Parallel Stack Deletion with Automatic Dependency Resolution\n\nWhen you specify multiple stacks (via the `-s` option or interactive mode `-i`), `delstack` automatically analyzes CloudFormation stack dependencies (via Outputs/Exports and Imports) and deletes stacks in parallel while respecting dependency constraints.\n\n### How It Works\n\n1. **Dependency Analysis**: Analyzes stack dependencies through CloudFormation Exports and Imports\n2. **Circular Dependency Detection**: Detects and reports circular dependencies before deletion\n3. **External Reference Protection**: Prevents deletion of stacks whose exports are used by non-target stacks\n4. **Dynamic Parallel Deletion**: Deletes stacks in dependency order with maximum parallelism\n\n### Deletion Algorithm\n\nThe deletion process uses a **reverse topological sort with dynamic scheduling**:\n\n```text\nExample: Stacks A, B, C, D, E, F with dependencies:\n  C → A (C depends on A)\n  D → A\n  E → B\n  F → C, D, E\n\nDeletion order (reverse dependencies):\n  Step 1: Delete F (no stacks depend on it)\n  Step 2: Delete C, D, E in parallel (after F completes)\n  Step 3: Delete B (after E completes)\n  Step 4: Delete A (after both C and D complete)\n```\n\n**Key Features**:\n\n- Stacks are deleted **as soon as all dependent stacks are deleted**\n- Multiple independent stacks are deleted **in parallel**\n- By default, there is **no limit** on the number of concurrent deletions\n- The `-n` option allows you to limit the maximum number of concurrent deletions if needed\n\n### Error Handling\n\n- **Circular Dependencies**: Detected before deletion starts, with the dependency cycle path reported\n- **External References**: If a target stack's export is imported by a non-target stack, deletion is prevented with a detailed error message\n- **Partial Failures**: If any stack fails to delete, all remaining deletions are cancelled\n\n## CDK Integration Details\n\nThe `delstack cdk` subcommand synthesizes a CDK app (or reads an existing `cdk.out`) and deletes all discovered stacks. It parses the Cloud Assembly manifest to determine stack names, regions, and dependencies.\n\n### Cross-region deletion\n\nWhen the CDK app deploys stacks to multiple regions (e.g., `us-east-1` for CloudFront + `ap-northeast-1` for the main app), `delstack cdk` automatically:\n\n1. Detects each stack's region from the Cloud Assembly manifest (`environment` field)\n2. Groups stacks by region and creates separate AWS sessions\n3. Resolves cross-region dependencies and deletes in the correct order\n4. Deletes independent regions in parallel\n\nFor environment-agnostic stacks (`unknown-region` in the manifest), the region from `-r` or the default AWS configuration is used.\n\n### Interactive mode\n\nWith `-i`, you can select which stacks to delete from all discovered stacks in the CDK app. Selected stacks are deleted in parallel with dependency resolution. Combined with `-f`, deletion protection and retain policies are automatically disabled before deletion:\n\n![delstack cdk interactive mode](https://github.com/user-attachments/assets/a440654d-109f-4ef1-a128-ea8905a4cfef)\n\n## GitHub Actions\n\nYou can use delstack in GitHub Actions Workflow. To delete multiple stacks, specify stack names separated by commas.\n\n\u003e **Note**: The `yes` option defaults to `true` in GitHub Actions because CI/CD environments cannot handle interactive prompts. Set `yes: false` only if you want the action to abort when a confirmation prompt would appear (e.g., TerminationProtection disable confirmation).\n\n```yaml\njobs:\n  delstack:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v3\n      - name: Configure AWS credentials\n        uses: aws-actions/configure-aws-credentials@v3\n        with:\n          role-to-assume: arn:aws:iam::123456789100:role/my-github-actions-role\n          # Or specify access keys.\n          # aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}\n          # aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n          aws-region: us-east-1\n      - name: Delete stack\n        uses: go-to-k/delstack@main # Or specify the version instead of main\n        with:\n          stack-name: YourStack\n          # stack-name: YourStack1, YourStack2, YourStack3 # To delete multiple stacks (deleted in parallel by default)\n          force: true # Force Mode to delete stacks including resources with the deletion policy Retain or RetainExceptOnCreate (default: false)\n          # yes: true # Skip confirmation prompts (default: true in GitHub Actions)\n          concurrency-number: 4 # Number of parallel stack deletions (default: unlimited)\n          region: us-east-1\n```\n\n### CDK mode\n\nTo delete stacks from a CDK app, set `cdk: true`. The action will run `cdk synth` and delete all discovered stacks. You can also pass CDK context values and specify an existing `cdk.out` directory.\n\n```yaml\njobs:\n  delstack:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v3\n      - name: Configure AWS credentials\n        uses: aws-actions/configure-aws-credentials@v3\n        with:\n          role-to-assume: arn:aws:iam::123456789100:role/my-github-actions-role\n          aws-region: us-east-1\n      - name: Setup Node.js\n        uses: actions/setup-node@v4\n        with:\n          node-version: \"22\"\n      - name: Install CDK\n        run: npm install -g aws-cdk\n      - name: Delete CDK stacks\n        uses: go-to-k/delstack@main\n        with:\n          cdk: true\n          # cdk-app: ./cdk.out           # Use existing cdk.out (skip synthesis)\n          # cdk-context: env=dev,foo=bar  # CDK context values (comma separated)\n          force: true\n          # yes: true  # default: true in GitHub Actions\n```\n\n### Raw commands\n\nYou can also run raw commands after installing the delstack binary.\n\n```yaml\njobs:\n  delstack:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Checkout code\n        uses: actions/checkout@v3\n      - name: Configure AWS credentials\n        uses: aws-actions/configure-aws-credentials@v3\n        with:\n          role-to-assume: arn:aws:iam::123456789100:role/my-github-actions-role\n          # Or specify access keys.\n          # aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}\n          # aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n          aws-region: us-east-1\n      - name: Install delstack\n        uses: go-to-k/delstack@main # Or specify the version instead of main\n      - name: Run delstack\n        run: |\n          echo \"delstack\"\n          delstack -v\n          delstack -s YourStack1 -s YourStack2 -r us-east-1\n```\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, adding new resource support, and coding conventions.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-to-k%2Fdelstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgo-to-k%2Fdelstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgo-to-k%2Fdelstack/lists"}