The package command packages your compute resources and prepares them for deployment without actually deploying. Use it to run the same packaging step that deploy uses — useful for catching packaging or build failures early, before committing to a full deployment.
Usage
The command loads your Stacktape configuration, initializes packaging, and packages all compute resources for the target stack. A valid Stacktape configuration file is required — by default Stacktape looks for one in the current directory.
To use a configuration file in a different location, pass --config.
The package command runs packaging with caching disabled, so every invocation produces a fresh build from the current state of your source code.
Examples
Package all compute resources for a staging stage in us-east-1:
Package with debug logging to see detailed build output:
Package using a specific AWS profile:
Package using a configuration file in a subdirectory:
Command reference
stacktape packageCLI 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, --stagerequiredstringStage
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.
-c, --configstringConfig 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.
--cwdstringCurrent 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, --helpstringShow 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.
--only-workloadsarrayOnly Workloads
Package only the specified workloads. Provide a comma-separated list of workload names to package.
Other workloads will be skipped. Example: --only-workloads myFunction,myContainer.
-p, --profilestringAWS 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.
--projectstringProject 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.
--quietbooleanQuiet
Hide progress, banners, success messages and hints. Command output, warnings and errors are still printed.
Related commands
deploy— creates or updates your stack on AWS. Usedeploywhen you want to deploy;packageruns the packaging step independently.synth— compiles your configuration into a CloudFormation template without packaging compute resources. Usesynthwhen you only need to inspect the infrastructure template.validate— validates your configuration and optionally includes workload packaging checks with--with-package.diff— previews what would change in your stack if you deployed. Useful alongsidepackagefor a full pre-deploy review.
package FAQ
When should I use package instead of just running deploy?
Use package when you want to verify that your compute resources package correctly before committing to a deployment — for example, catching build errors, confirming dependencies resolve, or validating that container images build successfully. In normal workflows, deploy handles packaging as part of its pipeline, so package is primarily a pre-deploy verification tool.
How is package different from validate --with-package?
validate validates your configuration, resolves resources, and synthesizes the CloudFormation template in memory. Adding --with-package also validates workload packaging. Use validate --with-package when you want configuration validation combined with packaging checks. Use package when you specifically want to run the packaging step on its own.
Does package use caching?
No. The package command runs packaging with caching disabled, so every invocation produces a fresh build from the current state of your source code. This ensures the output accurately reflects your code at the time of the run.
Does package require AWS credentials?
Only when your configuration reads something from AWS. package builds on your machine, so a typical project packages without AWS credentials and without any request to AWS. Credentials are loaded when packaging needs them: for a directive such as $Secret, $StackOutput or $AwsAccountId, or for a web framework build whose environment references deployed resources. Stacktape then uses the profile selected with --profile or AWS_PROFILE, or the standard AWS credential chain.
Can I package only specific workloads?
By default, the package command packages all compute resources in your configuration. To target a subset, pass --only-workloads with a comma-separated list of workload names (for example, --only-workloads myFunction,myContainer). Other workloads are skipped.
What is the difference between package and synth?
synth compiles your Stacktape configuration into a CloudFormation template — it produces the infrastructure definition but does not build any application code. package is the inverse: it builds your compute resources (according to each resource's packaging mode) but does not produce the infrastructure template. Run both before a deploy when you want a complete pre-deploy review.