cdkd state

cdkd state is the command family that talks to cdkd's S3 state store directly. Every subcommand reads the bucket rather than your CDK app, so none of them synthesizes and none of them needs the source that deployed a stack — which is what makes them work from a CI runner after the branch is gone, or from a laptop that never had the repository. The unit of work is the state record, not the stack in your app: cdkd state list shows everything the bucket knows about, and --all — on state destroy and state refresh-observed — acts across the whole estate in one invocation.

cdkd state info                          # which bucket, which region, how many stacks
cdkd state list                          # one "Stack (region)" per line
cdkd state list --tree                   # parent → child hierarchy for nested stacks
cdkd state resources MyStack             # logical id / type / physical id
cdkd state show MyStack --json           # the whole record, including properties
cdkd state destroy MyStack --yes         # delete the AWS resources, then the record
cdkd state orphan MyStack                # delete ONLY the record; AWS resources survive
cdkd state refresh-observed MyStack      # repopulate the drift baseline without deploying

Subcommands

Shared options

These rows are identical across the subcommands below, apart from state migrate, which takes neither --state-bucket nor --state-prefix. Each subcommand's own table lists only what is specific to it.

--region is deprecated — prefer AWS_REGION or your AWS profile — but it is still honored if passed, and it is not a no-op.

Two subcommands treat --region differently. cdkd state info does not accept it at all, and errors on it; the region it reports is the bucket's own, detected from S3. On cdkd state migrate it is a real selector rather than the deprecated option: it names which legacy bucket to migrate.

Every subcommand that acts on a named record — all of them except info, list, and migrate — also takes --stack-region <region>, which selects which of a name's records to use. It is deliberately not spelled --region: the deprecated global option picks the AWS client's region, whereas --stack-region picks which record to act on.

What happens when you omit it and the name has records in several regions is not uniform across the subcommands, so each one's table below states it.

cdkd state info

cdkd state info
cdkd state info --json

Answers "which bucket is cdkd actually using, and what is in it" — the bucket name, its region (auto-detected via GetBucketLocation), the source the name came from, the schema version, the record count, and the per-region cdkd bootstrap asset-storage opt-ins.

Routine commands (deploy, destroy, diff, …) do not print the bucket banner, because the default bucket name embeds your AWS account id and would leak through screenshots and public CI logs. cdkd state info is the explicit on-demand answer; --verbose surfaces the same name in the other commands' debug logs.

The Source: line names how the bucket was resolved — --state-bucket flag, CDKD_STATE_BUCKET env, cdk.json (context.cdkd.stateBucket), or one of the two defaults. The legacy default is called out as default (legacy region-suffixed name; cdkd state migrate recommended), which is the cue to run cdkd state migrate.

This subcommand degrades rather than failing: an unreadable bucket region reports unknown, and an empty bucket or an unparsable record reports an unknown schema version. The reported version is read from one record, not reconciled across all of them.

cdkd state list

cdkd state list                # one "Stack (region)" reference per line
cdkd state ls --long           # resource count, last-modified, lock status
cdkd state list --json
cdkd state list --tree         # parent → child tree for nested stacks
cdkd state list --tree --json  # the same tree, nested JSON

ls is an accepted alias. Note that cdkd list (also aliased ls) is a different question — it lists stacks from the local CDK app via synthesis, for CDK CLI parity, whereas cdkd state list reports what is registered in the S3 bucket.

cdkd state list's stdout is a payload in every mode, --json or not. The default one-reference-per-line shape is exactly what a while read -r ref loop consumes, so everything cdkd's logger prints goes to stderr instead. The other subcommands with a --json mode (resources, show, info) keep the --json gate, because their flagless output is a formatted human view rather than a record set. See Output streams: when stdout is a payload.

--tree walks each record's v6 parentStack / parentRegion fields, which a nested-stack deploy and the recursive cdkd import --migrate-from-cloudformation both populate, to draw tree(1)-style box-drawing:

NestedStackDeep (us-east-1)
└── NestedStackDeep~Child (us-east-1)
    └── NestedStackDeep~Child~Grandchild (us-east-1)

Flat output stays the default so scripts that grep cdkd state list keep working. A child whose parent record is missing — parent destroyed out-of-band, or state hand-deleted — surfaces at the root rather than vanishing. --long and --tree both read every record, so they cost extra S3 requests per stack — two for --long (the record and its lock), one for --tree. The plain listing reads none of them.

The equivalent low-level query, when you want it without cdkd:

aws s3 ls s3://cdkd-state-bucket/cdkd/ --recursive \
  | grep state.json \
  | awk '{print $4}' \
  | sed 's|cdkd/||; s|/state.json||'
# Output: <stackName>/<region>, one row per (stackName, region) pair.

cdkd state resources

cdkd state resources MyStack
cdkd state resources MyStack --long
cdkd state resources MyStack --json

Lists what cdkd recorded for one stack, sorted by logical id. The default view is three aligned columns — logical id, resource type, physical id — with no header row, which makes it pipe-friendly.

Resource properties are deliberately excluded from every mode here — use cdkd state show when you need them. A physical id may be a composite, pipe-delimited value for resource types AWS identifies by more than one field; see State Management for what those mean and why they are not what Ref returns.

cdkd state show

cdkd state show MyStack
cdkd state show MyStack --json
cdkd state show MyParent --show-nested
cdkd state show MyParent --show-nested --json

The deepest read: stack metadata, the lock record, outputs, and every resource with its properties, attributes, dependencies, and provisionedBy routing.

--show-nested reuses the same recursive walker as cdkd export: for every AWS::CloudFormation::Stack row in the target's resources it derives the child key <parent>~<childLogicalId>, loads cdkd/<parent>~<childLogicalId>/<region>/state.json, and recurses. Each descendant's block follows the parent's in depth-first order, flat at column zero rather than indented, behind its own header:

Stack: MyParent
  ...

Nested stack: MyParent~Child
Stack: MyParent~Child
  ...

It fails fast on a torn tree — a parent listing a nested-stack row whose child record does not exist — rather than printing a partial tree. Repair it by re-deploying the parent, by finishing whatever partial operation tore it, or, failing both, by cdkd state orphan <parent> and re-importing.

The --json shape under --show-nested is recursive {state, lock, children: [...]}, with children always present (an empty array on leaves) so the key set is stable. Without --show-nested the single-stack {state, lock} shape is preserved verbatim, so existing tooling keeps working.

A held lock never blocks any of the read subcommands; show reports it as part of the record.

cdkd state orphan

cdkd state orphan MyStack
cdkd state orphan MyStack --stack-region us-east-1
cdkd state orphan StackA StackB --force

Removes cdkd's state record for one or more stacks and leaves every AWS resource running. After this, cdkd no longer knows the stack exists; the resources become untracked rather than deleted.

-y / --yes skips the prompt but does not bypass the lock guard; only --force does both. A locked stack otherwise fails with the exact cdkd force-unlock command to run first. Orphaning a stack that has no record is a no-op, not an error, so the command is safe to re-run.

Force-releasing a lock this way deletes whatever lock is present, including a live one belonging to an in-flight deploy — deliberately, so a stuck lock can never make a record unremovable. The command warns when it is about to do that.

When to reach for it, and when not to: Orphan vs Destroy draws the line against cdkd orphan, which is synth-driven and works per resource; Cross-Stack References explains why it is the wrong tool for escaping a strong-reference destroy block.

cdkd state destroy

cdkd state destroy MyStack --yes
cdkd state destroy StackA StackB --yes
cdkd state destroy --all --yes
cdkd state destroy MyStack --remove-protection --yes

Deletes a stack's AWS resources and then its state record, reading the record instead of synthesizing — the CDK-app-free counterpart of cdkd destroy. Both run the identical per-stack pipeline, so the data guards, DeletionPolicy handling, strong-reference blocks, lock behavior, and exit codes are the same.

Three differences from cdkd destroy are worth knowing before you script it:

• Names only. Nothing is synthesized, so stacks are matched by physical CloudFormation name — CDK display paths and wildcards are not available. A nested-stack child can be targeted directly by its <parent>~<child> name.
• No -f / --force. -y / --yes is the only way to skip the prompts.
• No --purge-events. Use cdkd events prune to drop deployment-event history for a stack instead.

Naming a stack that has no record at all is an error, not a silent skip.

--all raises a single batch prompt listing every stack before anything is touched, and the per-stack prompts are then skipped. Interrupting at that prompt exits 130 with nothing read, locked, or deleted.

The flag semantics, the data guards, and the confirmation matrix are documented once, on the destroy page: Destroy flags & guards — in particular stack selection, confirmation prompts, --remove-protection, and skipped resources.

Note that cdkd state destroy records no deployment events at all — see Deployment Events.

The two per-resource duration flags behave exactly as they do on deploy; they are documented on Deploy: tuning.

cdkd state migrate

cdkd state migrate --region us-east-1 --dry-run
cdkd state migrate --region us-east-1
cdkd state migrate --region us-east-1 --remove-legacy

Copies a legacy region-suffixed state bucket (cdkd-state-{account}-{region}) into the region-free default (cdkd-state-{account}). This is a bucket-name migration, not a schema or key-layout one: objects are copied key-for-key and no record body is rewritten.

migrate --dry-run prints its plan — the two bucket names, the source bucket's real region, and the object count — and then still raises the confirmation prompt before stopping. refresh-observed --dry-run skips its prompt; this one does not, so an unattended preview needs -y alongside it.

The migration is idempotent: the destination is reused when it already exists, each object copy is idempotent per key, and the post-copy verification tolerates a destination that already holds objects, so a re-run resumes a partial migration. The source bucket is kept unless --remove-legacy is passed, and it is only deleted after the object count at the destination has been verified. Leave it in place until you are satisfied with the migrated bucket — that deletion is the one step here you cannot undo.

It refuses to start while any lock.json exists in the source bucket, naming the offending keys — wait for the in-flight operation, or clear a stale lock with cdkd force-unlock.

The full behavior list, the destination bucket's hardening, and the manual aws s3 sync fallback are on State Management.

cdkd state refresh-observed

cdkd state refresh-observed MyStack
cdkd state refresh-observed --all --dry-run
cdkd state refresh-observed --all --yes

Repopulates observedProperties for every resource in a stack by reading each one back from AWS, without deploying. observedProperties is the drift baseline: the snapshot of what AWS actually held, including AWS-managed defaults and keys your template never set.

Why it exists: cdkd deploy already maintains the baseline in two ways — it captures a fresh one for every resource it creates, updates, or replaces, and it reads back any resource whose baseline is missing, including ones that deploy left unchanged. Both of those reach only the resources whose provider can read state back. What deploy does not do is re-read a resource that was unchanged and already had a baseline; that one keeps whatever was captured the last time the resource was touched, however long ago.

This command re-reads the whole stack on demand, so it covers that case, and it is how you refresh a baseline without deploying at all — including on a stack deployed with --no-capture-observed-state, where nothing was captured in the first place.

The baseline is what makes the comparison thorough. With one present, cdkd drift walks the union of the recorded and the live keys, so a console-side edit to a key your template never mentions still surfaces; without one, it falls back to comparing only the keys in state.

Run cdkd scrub first on state written by a pre-GHSA binary. The readback is redacted by position against the existing record: the record's own properties are expected to hold the unresolved {{resolve:secretsmanager:...}} expression, which is written back over the decrypted value AWS echoes. A record whose properties already hold plaintext has nothing to redact from.

Resources whose provider cannot read current state, and resources AWS reports as not found, are counted as unsupported and keep their previous baseline — a transient not-found can never null one out. Per-resource read failures are reported individually and make the run exit 2.

Exit codes

Every mutating subcommand refuses its confirmation prompt with exit 1 in a non-interactive shell rather than hanging or assuming yes — pass -y / --yes (or --force, for state orphan) to run it unattended. The full cross-command table is in the CLI Reference.

Related

• State Store — the same subject, summarised for a first read
• State Management — the record schema, the key layout, and the lock mechanism
• Orphan vs Destroy — which of the four cleanup commands to reach for
• Destroy flags & guards — the guards and prompts cdkd state destroy inherits
• cdkd drift — the comparison state refresh-observed supplies the baseline for
• CLI Reference — every command and the full exit-code table
• Troubleshooting — what to do when a state record and AWS disagree