cdkd list

cdkd list prints the stacks a CDK app synthesizes, one per line, in dependency order. Run it to see what an app contains, or to feed stack names to a script. This page also documents the stack selection patterns that every command shares. cdkd ls is an alias.

# every stack, one id per line
cdkd list

# only the stacks directly inside one stage
cdkd list 'MyStage/*'

# each stack's name, account and region
cdkd list --long

# each stack's dependencies
cdkd list --show-dependencies

# the same payload as JSON
cdkd list --long --json

The command changes nothing in AWS, but it does call AWS. Synthesis resolves the account through STS and runs the context lookups the app asks for, so --profile and --role-arn matter here too.

Options

Selecting stacks

You select stacks by name or by pattern, and every command that takes stack arguments matches them the same way: deploy, diff, destroy, publish-assets, scrub, synth and list. The rules are the ones the AWS CDK CLI uses.

cdkd list MyStage/Api               # one stack, by its CDK path
cdkd list 'MyStage/*'               # every stack directly inside a stage
cdkd list '**'                      # every stack, at any depth
cdkd list MyStage-Api MyStage-Db    # several, by exact physical name

cdkd matches a pattern against the stack's hierarchical id, which is its path in the CDK app. A top-level stack has the id Api. A stack inside a Stage named MyStage has the id MyStage/Api.

Quote a pattern that contains a wildcard, so that the shell passes it to cdkd unchanged. Under zsh an unmatched glob aborts the command.

Edge cases

• A stack whose stackName differs from its construct id. A top-level stack is named by its construct id, as in cdk deploy.
• Physical names are matched exactly. Selecting by physical name is a cdkd extension, and it takes no wildcards. 'MyStage-*' is matched against hierarchical ids only.
• A pattern that is one stack's path and another stack's physical name. The stack whose path it is gets selected.
• Characters other than *. Each matches only itself.

Differences from cdk

--all

--all does not select the same stacks on every command:

On deploy, destroy and diff, cdkd prints one line that names any Stage stacks --all left out. To include them, name them with 'MyStage/*' or '**'. Those three commands refuse --all on an app whose every stack is inside a Stage.

Older cdkd versions let * cross /, so '*' and 'MyStage-*' reached Stage stacks. When deploy or destroy leaves out a stack that the old rule would have selected, it warns in one line. The warning names those stacks and the pattern that selects them.

What it prints

The default output is one id per line. A stack inside a CDK Stage has a path and a physical name that differ, and its line carries both:

Network
MyStage/Api (MyStage-Api)
MyStage/Db (MyStage-Db)

That form is for reading. To feed stack names to another command, take them from the structured output:

cdkd list --long --json | jq -r '.[].name' | while read -r name; do
  cdkd diff "$name"
done

--long and --show-dependencies print a structured document. It is YAML by default and JSON under --json.

The listing goes to stdout, and everything else goes to stderr. That includes progress lines such as Resolving missing context..., the CDK app's own stderr, and --verbose output. A redirect therefore captures the listing alone. See Output streams.

Edge cases

• Account ids in YAML. The structured document parses back unchanged. An AWS account id is a string in it, so YAML quotes the id (account: "123456789012"), which matches --json.
• Invisible characters under --json. A control, format, line-separator or paragraph-separator character left in a value, such as a zero-width space, is written as a \uXXXX escape.

Exit codes

cdkd judges matching over the whole set of patterns. cdkd list Good Bad prints Good and exits 0. The command fails only when every pattern misses, and the message then lists the patterns you gave and the stacks that exist.

Exit codes has the table for every command.

Related

• cdkd synth: reads the same app and prints templates
• cdkd diff: what a deploy of a listed stack would change
• Output streams: the commands whose stdout you can pipe
• CLI Reference: every command and the shared options