Skip to content

feat(cli): add --debug-app and --debug-cli flags#1604

Merged
mrgrain merged 1 commit into
mainfrom
mrgrain/feat/cli/multi-state-debug-flag
Jun 11, 2026
Merged

feat(cli): add --debug-app and --debug-cli flags#1604
mrgrain merged 1 commit into
mainfrom
mrgrain/feat/cli/multi-state-debug-flag

Conversation

@mrgrain

@mrgrain mrgrain commented Jun 5, 2026

Copy link
Copy Markdown
Contributor

Granular debug flags

The --debug flag now splits into two independent targets:

  • --debug-app — Sets CDK_DEBUG=true for the synthesized app. Logs additional information during synthesis (e.g. token creation stack traces). Slows down synthesis.
  • --debug-cli — Enables verbose AWS SDK tracing in the CLI itself.

--debug continues to work as before and implies both --debug-app and --debug-cli.

Configuration

The flags are also available in cdk.json / ~/.cdk.json:

{
  "debugApp": true,
  "debugCli": true
}

An existing "debug": true in config files implies both targets for backwards compatibility.

cdk doctor improvements

cdk doctor now reports some CLI configuration (verbosity level, active debug targets).

$ cdk doctor --debug
image

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license

@aws-cdk-automation aws-cdk-automation requested a review from a team June 5, 2026 10:51
@github-actions

github-actions Bot commented Jun 5, 2026

Copy link
Copy Markdown
Contributor

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

Comment thread packages/aws-cdk/lib/cli/util/debug.ts Outdated
Comment thread packages/aws-cdk/lib/cli/cli.ts Outdated
Comment thread packages/aws-cdk/lib/cli/cli.ts Outdated
@rix0rrr

rix0rrr commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

This is additive rather than breaking: a bare --debug is unchanged, and --debug=app/--debug=cli previously coerced to false under the boolean option, so they did nothing before.

At the expense of losing the way to write --debug app I suppose? It must be written as --debug=app ?

@mrgrain mrgrain marked this pull request as draft June 10, 2026 13:02
auto-merge was automatically disabled June 10, 2026 13:02

Pull request was converted to draft

Comment thread packages/@aws-cdk/toolkit-lib/lib/api/cloud-assembly/environment.ts Outdated
Comment thread packages/aws-cdk/lib/cli/cli-config.ts Outdated
Comment thread packages/aws-cdk/lib/cli/cli.ts Outdated
Comment thread packages/aws-cdk/lib/cli/cli.ts Outdated
Comment thread packages/aws-cdk/lib/cli/user-input.ts Outdated
Comment thread packages/aws-cdk/lib/commands/doctor.ts
Comment thread packages/aws-cdk/lib/commands/doctor.ts Outdated

@mrgrain mrgrain left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Almost there, but the whole--debug implies both targets things needs better modelling. we can change the configuration generator package.

@mrgrain

mrgrain commented Jun 11, 2026

Copy link
Copy Markdown
Contributor Author

Reworked the --debug implication into the config generator as you suggested. @aws-cdk/user-input-gen now supports an option-level implies field, and debug declares implies: ['debug-app', 'debug-cli']. The generator emits a yargs middleware (yargsImplies) that switches the implied flags on during parsing, so by the time anything reads argv, debugApp/debugCli are already true — no hand-written argv.debug || ... anywhere. A config-file debug: true is normalized to both targets when settings are assembled, and environment.ts keys CDK_DEBUG off debugApp only. All comment threads addressed and resolved.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is always shown, removing the double up

Split the `--debug` flag into `--debug-app` (sets CDK_DEBUG, enables
app-level tracing) and `--debug-cli` (enables AWS SDK tracing). The
existing `--debug` flag now implies both via a new `yargsImplies`
middleware.

Config file backwards compatibility is preserved: `debug: true` in
cdk.json implies both targets.

Also adds configuration reporting to `cdk doctor` and extracts
`shouldDisplayVersionMessage()` for cleaner version display logic.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants