feat(cli): make --debug a multi-state flag (--debug=app, --debug=cli)#1604
Open
mrgrain wants to merge 5 commits into
Open
feat(cli): make --debug a multi-state flag (--debug=app, --debug=cli)#1604mrgrain wants to merge 5 commits into
mrgrain wants to merge 5 commits into
Conversation
The --debug flag now accepts an optional target so users can scope debug output. `--debug` (or `--debug=all`) debugs everything, `--debug=app` only sets CDK_DEBUG for the app, and `--debug=cli` only enables verbose AWS SDK tracing in the CLI. This keeps the simple "just run with --debug" experience while allowing the granularity needed to isolate whether an issue is in the CDK app or the CLI itself. A bare --debug is rewritten to --debug=all before parsing so the underlying string option never greedily consumes a following positional argument (e.g. a stack name), preserving today's behavior for `cdk deploy --debug MyStack` and `cdk --debug deploy`.
Contributor
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
Frame the flag as a general troubleshooting tool and lead with the warning that it slows everything down, rather than enumerating implementation details.
`commandLineArgumentsToSettings` types `argv.debug` as `unknown`, so the debug helpers must accept `unknown` rather than `string | boolean | undefined`. The implementations already narrow the value safely.
mrgrain
commented
Jun 5, 2026
mrgrain
commented
Jun 5, 2026
mrgrain
commented
Jun 5, 2026
Comment on lines
+105
to
+111
| if (!isRecognizedDebugValue(argv.debug)) { | ||
| await ioHost.defaults.warn( | ||
| `Unrecognized value '${argv.debug}' for --debug; enabling full debug output. ` + | ||
| `Expected no value, or one of: ${DEBUG_VALUE_CHOICES.map((c) => `--debug=${c}`).join(', ')}. ` + | ||
| 'Note that --debug takes its value with "=" (e.g. --debug=app), otherwise the following argument may be consumed.', | ||
| ); | ||
| } |
Contributor
Author
There was a problem hiding this comment.
can we integrate this with the unknown options check? it feels different than yargs as well.
Contributor
Author
There was a problem hiding this comment.
I dropped the bespoke warning entirely rather than integrating it. After normalizeDebugArgs rewrites a bare --debug to --debug=all, the only way to hit an unrecognized value is an explicit --debug=typo, and interpretDebug already fails open to full debug — so a silent fail-open felt cleaner than a yargs-flavoured message. Happy to wire it into the unknown-options warning instead if you'd prefer an explicit heads-up.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
When something unexpected happens during a
cdkrun, the natural instruction to give a user is simply "run again with--debug". Until now that single switch turned on bothCDK_DEBUG(extra information from the CDK app during synthesis) and verbose AWS SDK tracing from the CLI at the same time, with no way to ask for just one. When troubleshooting it is often useful to know whether the problem lives in the CDK app or in the CLI itself, and the combined output makes that harder than it needs to be.This change keeps
--debugworking exactly as before (it still debugs everything), but turns it into a multi-state flag so the output can be scoped.--debug=apponly setsCDK_DEBUGfor the app, and--debug=clionly enables AWS SDK tracing in the CLI.--debug=allis accepted as an explicit synonym for the bare flag. The intent is to preserve the simple "just add--debug" experience as the default, while giving people who already know where to look a way to cut down the noise.The reason the flag is implemented as a string option rather than a boolean is that yargs has no option type that both carries an optional
=valueand behaves like a bare boolean. A plain string option would greedily consume the next token, socdk deploy --debug MyStackwould treatMyStackas the debug value and drop the stack selector. To avoid that regression a bare--debugis rewritten to--debug=allbefore the arguments reach yargs, which guarantees the flag always carries an explicit value and never swallows a following positional argument. This keepscdk deploy --debug MyStackandcdk --debug deploybehaving as they do today. An unrecognized value (for example a typo) falls open to full debug output and emits a warning rather than failing the command.This is additive rather than breaking: a bare
--debugis unchanged, and--debug=app/--debug=clipreviously coerced tofalseunder the boolean option, so they did nothing before.Fixes #
Checklist
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license