Compatibility Promise
cdkd follows semantic versioning from v1.0.0 on. This page lists what a minor or patch release keeps compatible, which changes wait for the next major version, and what is not covered at all.
Important
This promise applies from v1.0.0. It makes no promise about 0.x releases, where a minor release can still change any of the items below.
cdkd --version # the version you are on
cdkd diff --all --json | jq '.[].stack' # a covered JSON shape
cdkd deploy MyStack; echo "exit $?" # a covered exit code
What a release may change
| Release | May contain |
|---|---|
| Patch | Bug fixes that keep every covered item as documented. |
| Minor | New commands, flags, JSON fields, configuration keys and environment variables; a state schema bump, migrated automatically; a feature that needs a newer bootstrap (cdkd bootstrap), or a security fix that needs a bootstrap re-run (cdkd bootstrap --force when it changes existing resources); dropping an end-of-life Node.js major; deprecations. |
| Major | Anything that removes or changes a covered item, including a changed default. |
A bug fix can still change behaviour that contradicts these docs. The docs describe the intended behaviour, and the fix brings cdkd back to it.
What is covered
Commands and flags
Every command and flag listed in the CLI Reference, except those in Experimental features, is covered: its name, its arguments, and its default value. A minor release does not remove or rename one, and does not change what an existing flag does or defaults to.
A minor release may add a command, a flag or a new value for an existing
flag. cdkd <command> --help lists the flags of the version you run.
Exit codes
The meaning of each code in Exit codes is covered. A situation that exits with one code keeps exiting with that code; moving it to another code needs a major release.
JSON output
The documented fields of each machine-readable output are covered: their names, their types and their meaning.
| Output | Shape |
|---|---|
cdkd diff --json |
cdkd diff: JSON output |
cdkd drift --json |
cdkd drift: JSON output |
cdkd list --long --json, --show-dependencies --json |
The structured document |
cdkd state info --json |
cdkd state info |
cdkd state list --json |
--json on its own |
cdkd state list --long --json, --tree --json |
cdkd state list |
cdkd state resources --json |
cdkd state resources |
cdkd state show --json |
cdkd state show: {state, lock}, the state record and its lock |
cdkd events <stack> --json |
The run list |
cdkd events <stack> --run <id> --json |
Deployment Event Format: an array, one object per event |
| Which commands print only the document to stdout | Output streams |
A minor release may add a field, and may add a value to a field that holds one of a set of values. A script should ignore fields it does not know. Removing or renaming a field, changing its type, or changing what an existing value means needs a major release.
An output or a field that this table's pages do not document is not covered.
The state bucket and the state schema
The bucket layout in What is in the bucket and the fields in What a state record contains are covered. Outside a state schema bump, a minor release only adds objects to the bucket and fields to a record.
A state schema bump lands in a minor release and migrates automatically: a newer cdkd reads every older record and saves it in the format Schema versions and upgrades describes the next time it writes, with no command to run.
From v1.0.0, a cdkd release can read a record that a newer release wrote when that record's schema bump only added fields. A command that would write such a record fails before it changes anything, with an error that names the newer version and says to upgrade cdkd. Any other bump is still refused by an older cdkd, so upgrade every machine and CI job that deploys the stack, or reads its outputs, together. Schema versions and upgrades lists the versions and what each added.
Configuration: cdk.json and environment variables
These cdk.json keys are covered:
| Key | Page |
|---|---|
app |
Options every command takes |
context (passed to the app) |
Running the app |
requireApproval |
--require-approval |
outputsFile |
Read Stack Outputs |
context.cdkd.stateBucket |
Which bucket cdkd uses |
context.cdkd.autoAssetStorage |
Auto-create on first deploy |
context.cdkd.useCdkBootstrapAssets |
Keeping CDK bootstrap destinations |
context.cdkd.prefixUserSuppliedNames |
--prefix-user-supplied-names |
context.cdkd.captureObservedState |
--no-capture-observed-state |
context.cdkd.noPrefixUserSuppliedNames (deprecated) |
--prefix-user-supplied-names |
These environment variables are covered:
| Variable | Page |
|---|---|
CDKD_APP |
Options every command takes |
CDKD_STATE_BUCKET |
Which bucket cdkd uses |
CDKD_ROLE_ARN |
--role-arn |
CDKD_PREFIX_USER_SUPPLIED_NAMES |
--prefix-user-supplied-names |
CDKD_NO_PREFIX_USER_SUPPLIED_NAMES (deprecated) |
--prefix-user-supplied-names |
CDKD_NO_LIVE |
Troubleshooting |
CDKD_PHASE_TIMINGS |
Slow deploys, throttling and retries |
CDKD_CR_AUTHZ_MAX_RETRIES |
Slow deploys, throttling and retries |
CDKD_ACM_POLL_ATTEMPTS, CDKD_ACM_POLL_INTERVAL_MS |
Failures during a deploy |
CDKD_CR_S3_ENDPOINT_URL |
The custom-resource response endpoint |
CDKD_ALLOW_SECRETS_ON_ARGV |
Local Execution |
CDKD_SHADOW_READY_TIMEOUT_MS |
cdkd local start-service |
A covered key or variable keeps its name and meaning. The default of a poll,
retry or timeout variable is not covered, and neither is the report
CDKD_PHASE_TIMINGS prints. A cdk.json key or CDKD_* variable that is not
in these two tables, including one cdkd sets for itself, is not covered.
Bootstrap resources
The resources in
What bootstrap creates are
covered: what bootstrap creates and the default names. A minor release may
tighten their configuration, such as a bucket policy. An existing resource
gets the tightened configuration when you run cdkd bootstrap --force
(Re-running bootstrap).
From v1.0.0, re-running cdkd bootstrap after an upgrade follows these
rules:
- A minor release never makes an existing deploy stop working only because
you did not re-run
cdkd bootstrap. - A minor release may add a feature that needs a resource or setting newer
than your bootstrap. Using that feature without it fails with an error
telling you to re-run
cdkd bootstrap. Deploys that do not use the feature keep working. - A minor release may require re-running bootstrap to apply a security fix.
Its release notes say so and name the command, and cdkd warns you. A fix
that changes resources bootstrap already created needs
cdkd bootstrap --force, because a plain re-run leaves them untouched. When the fix cannot wait, cdkd may stop before a deploy changes anything, with an error that names the command to run.
The CLI is the interface
From v1.0.0, the supported interface is the cdkd command. The modules
inside the npm package are not part of this promise and can change in any
release. Do not import them from a program.
Supported runtimes
| Runtime | Supported | Note |
|---|---|---|
| Node.js | 22.12 or later (engines: >=22.12.0) |
Node.js 22 reaches end of life on 2027-04-30. |
| AWS CDK | Cloud assemblies synthesized by AWS CDK v2 (aws-cdk-lib v2) |
See the schema note below. |
Dropping a Node.js major that has reached end of life is a minor release, and its release notes say so.
A cloud assembly whose schema version is newer than any the cdkd release was tested with is outside the supported range. cdkd does not check the version of the assembly it reads, so such an assembly may deploy, fail or behave differently, and the result is not covered by this page.
Experimental features
From v1.0.0, a feature that these docs explicitly mark as experimental is outside this promise. A minor release can change or remove it, and the release notes call that out. These are marked experimental:
| Feature | Page |
|---|---|
The AWS Emulator target: --aws-emulator, CDKD_AWS_EMULATOR and mixed mode |
Develop Locally with AWS Emulator |
cdkd refactor |
cdkd refactor |
cdkd orphan |
Orphan Instead of Destroy |
cdkd publish-assets |
cdkd publish-assets |
cdkd refactor, cdkd orphan and cdkd publish-assets follow AWS CDK CLI
commands that the CDK CLI still marks unstable, so cdkd changes with them.
Deprecation
A deprecated command, flag, key or variable keeps working for the rest of its major version, and prints a warning when you use it. It is removed only in the next major release, and that release's notes list it. There is no minimum time between the deprecation and the removal beyond that.
What is not covered
- Human-readable output: log lines, progress text, warnings, prompts, error
message wording, and the formatted views printed without
--json. --verboseoutput and anything written to stderr.- Timing and performance, including how many AWS calls a command makes.
- Outputs, fields and objects that the linked pages do not document, and keys or variables not in the tables above.
- The modules inside the npm package (see The CLI is the interface).
- The order in which a deploy or destroy works through a stack's resources.
Related
- CLI Reference: every command and the options all of them take
- Exit codes: what each code means
- State Store: the bucket and the record format
- Schema versions and upgrades: mixing cdkd versions on one stack
cdkd bootstrap: what bootstrap creates and how to re-run it