deploy

The stacktape deploy command deploys your stack to AWS. If the stack does not exist yet, it creates a new one. If it already exists, it updates it with the current configuration. This is the primary command for shipping changes to any stage — development, staging, or production.

Usage

stacktape deploy --stage <stage> --region <region>

Both --stage and --region are required. The command requires a valid Stacktape configuration file (usually stacktape.ts, with stacktape.yml still supported) in the current directory, or a path passed with --config.

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

What happens during deploy

  1. Validate — Reads your config, validates guardrails, and ensures referenced secrets exist.
  2. Build & package — Packages workloads for deployment. Cached artifacts are reused when possible.
  3. Upload — Uploads deployment artifacts for the stack.
  4. Deploy — Creates or updates a CloudFormation stack. When only code changed, updates the changed functions and container services directly instead (see Fast deployments).
  5. Post-deploy — Syncs hosting buckets, invalidates CDN caches, and prints resource URLs.

After a successful deploy, Stacktape prints short stack information and completion links, including a Stacktape Console URL for the deployed stack.

Fast deployments

When only the code of functions or container services changed, stacktape deploy updates them directly instead of through CloudFormation. A function update takes seconds; a container service runs a normal rolling deployment. Stacktape decides this on its own for every deployment, using CloudFormation whenever anything else changed. It prints the reason when it does.

Code that several functions share is packaged into a Lambda layer. A change to it is a code change too: Stacktape publishes the new layer version itself and gives every function that uses it the new version together with its own code, so a change to shared code deploys as fast as a change to one function.

When both a handler and its shared code change, Stacktape attaches the new layer before switching the handler if the old handler can use it. This includes adding a helper and using it in the new handler. When compatibility cannot be proved, Stacktape temporarily keeps both generations available. A failed code update can leave the old handler on the new layer; deploying again completes the update.

The compatibility check protects the forward deployment. CloudFormation updates code and layers separately during a rollback, so rolling back across an edit that added a used export can briefly fail invocations if the old layer is restored before the new handler is replaced. Stacktape prints a note during the fast deployment when it detects this risk. See rollback safety.

A deployment uses CloudFormation when:

  • the stack is new, or the template changes anything other than function code or container images built by Stacktape (configuration, environment variables, permissions, resources, external images),
  • stack settings changed, such as tags or termination protection,
  • a changed function uses an alias (deployment or provisioned concurrency) or a changed container service uses blue/green deployment,
  • the stack has an after:deploy deployment script, which runs through CloudFormation on every deployment,
  • you pass --full.

A fast deployment is a release like any other: it gets the next version number, and rollback can return to it or from it. A deployment that changes nothing creates no release, even with --full. If some updates fail, Stacktape still finishes the others and lists which workloads run the new code. Deploying again updates the rest. The CloudFormation template is updated by the next full deployment.

Common flags

--full

Deploys every change through CloudFormation, even when only code changed.

stacktape deploy --stage production --region eu-west-1 --full

--yes

Confirms the deploy when it needs confirmation: an update that may delete stateful resources, or a project that does not exist yet and would be created. Use --yes in CI/CD pipelines and other non-interactive runs. Without it, such a deploy fails with CONFIRMATION_REQUIRED before it changes anything. --agent only switches the output to JSONL; it does not confirm.

stacktape deploy --stage production --region eu-west-1 --yes

--auto-rollback

By default, a failed deployment keeps what it created or updated. The stack stays in CREATE_FAILED (first deployment) or UPDATE_FAILED (update), and running deploy again after fixing the error continues from the failure instead of creating everything again. With --auto-rollback, CloudFormation undoes this deployment if it fails: an update returns to the last successful deployment, and a first deployment deletes the new stack. The flag overrides deploymentConfig.autoRollback for one deployment.

stacktape deploy --stage production --region eu-west-1 --auto-rollback

To undo a failed update later, use stack recover. To remove a failed first deployment, use delete. To return to an earlier successful version, use rollback. See when a deployment fails.

--no-cache

Forces a fresh build of all compute resources, ignoring cached artifacts from previous deploys. Use this when you suspect a stale cache is causing issues.

stacktape deploy --stage dev --region eu-west-1 --no-cache

--config

Points to a Stacktape configuration file when it is not in the default location (current directory).

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

--no-layer-optimization

By default, Stacktape extracts shared code into Lambda layers to reduce per-function deployment size. Disable this to bundle all code directly into each Lambda function — useful if you need to inspect the full function package or if layer extraction causes issues.

--show-secrets

Includes secret values, such as database passwords and connection strings with credentials, in the --agent result (data.result.stackInfo) and in the stack-info file. Without it, each of them is <<OMITTED>>. Use it only where the output stays private, never in shared CI logs. The terminal summary never prints secret values.

All flags

stacktape deployCLI 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.

-s, --stagerequiredstring

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.

-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.

--auto-rollbackboolean

Auto-Rollback

If true, a failed deploy rolls back instead of keeping what it created. Overrides deploymentConfig.autoRollback for this deploy.

  • Without auto-rollback (default): A failed deploy keeps what it created or updated. The stack stays in CREATE_FAILED or UPDATE_FAILED, and the next deploy continues from there.
  • With auto-rollback (--auto-rollback): A failed update rolls back to the last successful deploy, and a failed first deploy deletes the stack. This is the default when deploymentConfig.triggerRollbackOnAlarms or monitoringTimeAfterDeploymentInMinutes is set.
--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.

--no-remote-cacheboolean

Disable Docker Remote Cache

In CI, image builds for an existing stack import and export Docker's layer cache in the stack's ECR repository, so a runner without a local build cache still reuses unchanged layers. Outside CI, Docker's local build cache is used and nothing is cached in ECR. Set to true to build without the ECR cache in CI as well.

--no-layer-optimizationboolean

Disable Layer Optimization

If true, disables the shared Lambda layer optimization. By default, Stacktape extracts shared code into Lambda layers to reduce deployment size. Use this flag to bundle all code directly into each Lambda function.

--docker-argsarray

Docker Arguments

Additional arguments to pass to the docker run or docker build commands.

--fullboolean

Full Deploy

If true, deploys every change through CloudFormation. By default, when only the code of functions and container workloads changed, Stacktape updates them directly, which takes seconds instead of minutes. Changes to infrastructure always use CloudFormation.

-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.
--no-cacheboolean

No Cache

If true, disables the use of cached artifacts and forces a fresh build of compute resources.

--keep-temp-filesboolean

Preserve Temporary Files

If true, preserves the temporary files generated by the operation, such as the CloudFormation template and packaged resources. These files are saved to .stacktape/[invocation-id].

-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.

--runner"local" | "ec2"

Deploy Runner

Controls where deployment build and packaging work runs.

  • local: Run deployment locally.
  • ec2: Run deployment on a configured EC2 runner in your AWS account.
--show-secretsboolean

Show Secrets

If true, the command includes secret values in its output: database passwords, connection strings with credentials and other stack parameters Stacktape stores as sensitive, and the value a secret get reads. Without it, each of them is <> in the terminal, in JSON output and in the stack-info file. Use it only where the output stays private, never in shared CI logs.

--skip-release-commandboolean

Skip Release Command

If true, this deploy does not run the releaseCommand of any service. Use it when you already ran the command yourself, or to deploy a fix for the command. The next deploy without this flag runs it.

Examples

Deploy a new production stage

stacktape deploy --stage production --region us-east-1

Deploy to the account of an AWS profile

The deploy goes to the connected AWS account that my-aws-profile belongs to. It fails if that account is not connected to your organization.

stacktape deploy --stage staging --region eu-west-1 --profile my-aws-profile --project my-app

Deploy to a named connected account

stacktape deploy --stage production --region eu-west-1 --aws-account production

Deploy everything through CloudFormation

stacktape deploy --stage production --region eu-west-1 --full

Non-interactive deploy in CI/CD

stacktape deploy --stage production --region us-east-1 --yes

Preview changes before deploying

Use diff to see what a deploy would modify without actually applying changes:

stacktape diff --stage production --region us-east-1

Free plan cost limit

A Free organization cannot deploy once its managed AWS costs for the current calendar month (UTC) are above $100. The deploy stops before it touches AWS with a Free Plan Limit Reached error that shows this month's costs, the limit and the link to upgrade:

[x] Free Plan Limit Reached

Deploys are paused. This organization is on the Free plan, and the AWS costs Stacktape manages for it are
$142.17 in October 2026 (UTC), above the plan's limit of $100 a month.

Upgrading to the Flexible plan lifts the limit immediately; otherwise deploys resume when the next month starts. delete and rollback keep working, and running infrastructure is not affected. See Free plan cost limit for what counts.

Dev stacks cannot be deployed

Stages created by stacktape dev (dev stacks) cannot be updated with deploy. If you attempt this, Stacktape rejects the deploy with an error. To deploy a production stack, use a different stage name (e.g., --stage production). To remove a dev stack, use stacktape delete.

Stacktape does not currently check CloudFormation resource drift before deploying. Manual changes to stack resources can affect an update; review the proposed changes with diff.

CommandDescription
diffShows what a deploy would change without applying anything.
rollbackRolls back to a previous Stacktape deployment version.
stack recoverRecovers a CloudFormation stack stuck in UPDATE_FAILED or UPDATE_ROLLBACK_FAILED state.

For eligible Node.js Fargate web services, properties.codeSwap: true enables in-place code swaps with the same deploy command. The opt-in applies in every stage, including production, within the task cap. Failed memory screening or an unsupported change uses an image deploy, with the reason in CLI output. Old and new processes share memory during a swap; a sudden memory increase can fail in-flight requests.