The stacktape synth command compiles your Stacktape configuration into a CloudFormation template and writes it to a local file. Use it when you need the generated CloudFormation template on disk for inspection or downstream tooling. No stack is created or modified.
Usage
This reads your Stacktape configuration, resolves all resources, finalizes the CloudFormation template, and writes it to compiled-template.yaml. Both --stage and --region are required so the command can resolve a concrete stack context.
To write the template to a custom path, use --out.
Unlike deploy, synth does not create or modify any stack resources. It does not require a previously deployed stack, and it does not require a Stacktape subscription.
Flags reference
stacktape synthCLI 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.
-o, --outstringOutput File
The path to the file where the operation output will be saved.
--keep-temp-filesbooleanPreserve 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, --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.
Important flags
--out
Controls where the synthesized template is saved. Defaults to compiled-template.yaml. Use this when you want the template in a specific location for CI artifacts, version control, or external tooling.
--config
Points to your Stacktape configuration file when it is not in the default location. The path is relative to the current working directory.
--keep-temp-files
When set, Stacktape preserves temporary files generated during synthesis under .stacktape/[invocation-id]. Useful for debugging the synthesis pipeline when the final template doesn't match your expectations.
--project
Specifies the Stacktape project name for the operation. Pass the same value you would use with deploy.
Examples
Synthesize a production template and save it to a specific directory:
Synthesize with debug-level logging to troubleshoot configuration resolution:
Synthesize using a specific AWS profile:
Synthesize and keep temporary files for inspection:
synth vs validate vs diff
| Command | What it does | Writes a file? | Modifies stack? | Requires deployed stack? |
|---|---|---|---|---|
synth | Compiles config into a CloudFormation template | Yes (compiled-template.yaml) | No | No |
validate | Validates the Stacktape project without writing deployment artifacts | No | No | No |
diff | Shows what would change if you deployed | No | No | Yes |
Use synth when you need the template file on disk for inspection or downstream tooling. Use validate for a quick pass/fail check without writing artifacts. Use diff when you want to compare your current config against what is already deployed.
Related commands
validate— validates your Stacktape project without writing deployment artifacts. Use--thoroughto validate workload packaging and ask AWS CloudFormation to validate the synthesized template.diff— previews what would change in your deployed stack if you randeploywith the current configuration.deploy— deploys (or updates) your stack to AWS. Internally runs the same synthesis step thatsynthperforms.
synth FAQ
Why are --stage and --region required if nothing is deployed?
Stacktape needs both values before synthesis so it can resolve a concrete stack context. Your configuration may use the stage and region in resource names, conditional logic, or directive expressions, so different stages can produce different templates. Pass the same values you would use for deploy or validate.
Can I feed the synthesized template into CloudFormation linting or policy tools?
Yes — that is a primary use case. The output is a finalized CloudFormation YAML template, so you can pass it to any tool that accepts CloudFormation: linters, policy-as-code scanners, or your own scripts. A common CI pattern is to run synth and then run a scanner against the output. In non-TTY environments output is plain text automatically; pass --output-format plain to force it, or --agent for JSONL.
When should I use synth vs validate vs diff?
Use synth when you need the generated CloudFormation template on disk to inspect or feed to external tooling. Use validate for a quick pass/fail check without writing any artifact. Use diff when a stack is already deployed and you want to see what would change on the next deploy — unlike synth, diff compares against live stack state.
The synthesized template doesn't match what I expected — how do I debug it?
Run synth with --keep-temp-files to keep the intermediate files generated during synthesis under .stacktape/[invocation-id], and add --debug to trace how your configuration is resolved. This lets you inspect the synthesis pipeline rather than only the final template.