delete

The stacktape delete command permanently removes a deployed stack and all its AWS resources. It deletes deployment artifacts recorded for the stack, then deletes the CloudFormation stack, and then the stack's deployment bucket and ECR repository. Stacktape creates these outside the stack for new stacks; in older stacks CloudFormation deletes them with the stack. Back up any data you need before running this command — the operation is irreversible.

Usage

stacktape delete --stage production --region eu-west-1

--region is the only required flag. To avoid deleting the wrong stack, pass the identifying flags you normally use, such as --stage, --project, and --config when applicable.

The delete command removes all resources managed by the stack according to CloudFormation's deletion behavior. Back up or export anything you need before deletion — this operation cannot be undone.

Important flags

--yes — Skips the interactive confirmation prompt. Required for CI/CD and non-interactive scripts.

--config — When provided, Stacktape loads the configuration file and runs any beforeDelete lifecycle hooks before deletion. Without it, hooks are skipped.

stacktape deleteCLI options
-r, --regionrequired"us-east-2" | "us-east-1" | "us-west-1" | "us-west-2" | "ap-east-1" | "ap-south-1" | "ap-northeast-3" | "ap-northeast-2" | "ap-southeast-1" | "ap-southeast-2" | "ap-northeast-1" | "ca-central-1" | "eu-central-1" | "eu-west-1" | "eu-west-2" | "eu-west-3" | "eu-north-1" | "me-south-1" | "sa-east-1" | "af-south-1" | "eu-south-1"

AWS Region

The AWS region for the operation. For a list of available regions, see the AWS documentation.

Inside a project whose config declares region, the flag is optional and overrides the config.

-y, --yesboolean

Auto-Confirm Operation

Confirms an operation that would otherwise ask first: deleting a stack, an update that may delete stateful resources, creating a project that does not exist yet, and the other deletions that ask. Without a terminal to ask in (CI, --agent, machine-readable output), such an operation fails with CONFIRMATION_REQUIRED unless this flag is set. --agent does not confirm anything.

--aws-accountstring

AWS Account

The name of the AWS account to use for the operation. The account must first be connected in the Stacktape Console.

Without it, the account is chosen by --profile, AWS_PROFILE or AWS credentials in environment variables, then by your saved default, then by your organization's only connected account. --aws-account takes precedence over all of them, but AWS credentials in environment variables must then belong to that account.

-c, --configstring

Config File Path

The path to your Stacktape configuration file, relative to the current working directory. Without it, Stacktape uses the one stacktape.ts, stacktape.yml, stacktape.yaml or stacktape.js in the working directory. When there are several, the command stops and asks you to choose one with this option.

--cwdstring

Current Working Directory

The working directory for the operation. All file paths in your configuration will be resolved relative to this directory. By default, this is the directory containing the configuration file.

-h, --helpstring

Show Help

If provided, the command will not execute and will instead print help information.

--log-level"info" | "debug" | "error"

Log Level

The level of logs to print to the console.

  • info: Basic information about the operation.
  • error: Only errors.
  • debug: Detailed information for debugging.
-p, --profilestring

AWS Profile

The AWS profile to use for the command. You can manage profiles using the aws-profile:* commands and set a default profile with defaults set.

For commands that use a connected AWS account, --profile (or AWS_PROFILE) selects the connected account the profile belongs to, unless --aws-account is set. The command fails if that account is not connected.

--projectstring

Project Name

The name of the Stacktape project for this operation.

Commands that target a stack take it from projectName in the project's config when the flag is absent.

--quietboolean

Quiet

Hide progress, banners, success messages and hints. Command output, warnings and errors are still printed.

-s, --stagestring

Stage

The stage for the operation (e.g., production, staging, dev-john). You can set a default stage using the defaults set command. Stage names use lowercase letters, numbers and dashes, with at least 2 characters. The project name, a dash and the stage form the CloudFormation stack name, which can have at most 128 characters. Stacktape shortens an AWS resource name that would be too long and adds a hash.

Lifecycle hooks

When a configuration file is loaded, Stacktape registers configured hooks before artifact and stack deletion. The command description documents these as beforeDelete hooks. This is useful for exporting data, cleaning up external resources, or notifying other systems before the stack is torn down.

Without a configuration file, beforeDelete hooks are not executed.

Termination protection

Deletion fails when the CloudFormation stack has EnableTerminationProtection set. To proceed, first deploy an update with the terminationProtection property set to false, then run the delete command again.

Deletion protection

Deletion also stops, before anything is deleted, when a resource of the stack has deletion protection on, such as a relational database or Aurora DSQL database with deletionProtection: true. The error lists the protected resources. Deploy with deletionProtection: false, then run the delete command again. When an earlier delete already failed with DELETE_FAILED, the stack cannot be deployed, so turn the protection off in AWS instead.

Examples

Delete a staging stack.

stacktape delete --stage staging --region eu-west-1

Delete with automatic confirmation, suitable for CI/CD pipelines.

stacktape delete --stage staging --region eu-west-1 --yes

Delete with hooks enabled by providing the config file.

stacktape delete --stage production --region eu-west-1 --config ./stacktape.ts

Delete from the connected AWS account that an AWS profile belongs to.

stacktape delete --stage dev-john --region us-east-1 --profile my-aws-profile

Enable debug-level logging for troubleshooting.

stacktape delete --stage staging --region eu-west-1 --debug
  • deploy — Create or update a stack.
  • rollback — Roll back to a previous deployment version instead of deleting.
  • stack list — List all deployed stacks in a region to find what to delete.

delete FAQ

What happens to my data when I delete a stack?

The delete command deletes deployment artifacts and then deletes the CloudFormation stack, so resources and data managed by that stack are removed according to CloudFormation's deletion behavior. There is no undo. Export or back up anything you need before running the delete command.

Can I delete a stack without a configuration file?

Yes. The config file is optional — you can identify the stack with --project, --stage, and --region directly. The trade-off is that beforeDelete lifecycle hooks only run when you pass --config, so without it any data export or cleanup hooks are skipped.

How do I delete a stack in a CI/CD pipeline?

Add --yes to confirm the deletion in CI/CD or other non-interactive scripts. Example: stacktape delete --stage staging --region eu-west-1 --yes. Without --yes, a run that cannot ask (no terminal, --agent or machine-readable output) fails with CONFIRMATION_REQUIRED and deletes nothing. --agent only switches the output to JSONL; it does not confirm the deletion.

How do I delete a stack with termination protection?

Deletion fails when the CloudFormation stack has EnableTerminationProtection set. First deploy an update with the terminationProtection property set to false, then run the delete command again.

What is the difference between delete and rollback?

The rollback command reverts your stack to a previous deployment version while keeping the stack alive. The delete command permanently removes the entire stack and all its resources. Use rollback when you want to undo a bad deploy; use delete when you want to completely remove the stack from AWS.