(cli): --json is a global option but is silently ignored by most commands
- Dominant language
- TypeScript
- Stars
- 105
- Forks
- 122
- Avg merge
- 1d 17h
- Merged PRs (30d)
- 71
Description
## Describe the bug
`--json` (`-j`) is declared as a **global** CLI option, which makes it appear available on every `cdk` command in help output and causes it to be accepted (without error) on any command. In reality there is no generic mechanism that serializes command output as JSON. Only a handful of commands actually read the flag and opt in by hand:
- `context`
- `list` / `ls`
- `bootstrap` (via `--show-template`)
- `synth` / `synthesize`
- `metadata`
For every other command (`deploy`, `diff`, `drift`, `destroy`, `import`, `gc`, `rollback`, etc.) `--json` is accepted but silently ignored. This is misleading: users reasonably assume a global option affects all commands, so they may pass `cdk deploy --json` expecting machine-readable output and instead get ordinary output with no error and no indication the flag did nothing.
The flag's own description already hints that its scope is narrow — "Use JSON output instead of YAML when templates are printed to STDOUT" — yet it is registered globally.
## Regression Issue
- [ ] Select this option if this issue appears to be a regression.
## Last Known Working CDK Version
N/A
## Expected Behavior
`--json` should only be available on the commands that actually honor it (`context`, `list`/`ls`, `bootstrap`, `synth`, `metadata`). Passing `--json` to a command that does not support it should either not be accepted (yargs reports an unknown option) or be clearly documented as unsupported — rather than being silently ignored.
## Current Behavior
`--json` is a global option. Passing it to a command that does not read it (e.g. `cdk deploy --json`) is accepted silently and has no effect on the output.
## Reproduction Steps
```sh
# Accepted, but has no effect — output is unchanged and no warning/error is shown:
cdk deploy --json
# Contrast with a command that actually honors it:
cdk ls --json
```
## Possible Solution
Move `--json` from the global options block in `packages/aws-cdk/lib/cli/cli-config.ts` into the per-command option definitions for the commands that consume it (`context`, `list`/`ls`, `bootstrap`, `synth`/`synthesize`, `metadata`). Regenerate the argument parser via `@aws-cdk/user-input-gen`.
Note this is an observable CLI-surface change: commands that currently accept `--json` as a no-op would begin rejecting it as an unknown option. This likely warrants a feature flag or a deprecation window to preserve backwards compatibility, per the repo's backwards-compatibility policy.
## Additional Information/Context
Discovered while adding a generic guard to the integration-test harness (`fixture.cdk()`) that asserts `--json` output is JSON-parseable. Because the flag is a no-op on most commands, the guard can only meaningfully be applied to the commands listed above.
## CDK CLI Version
N/A (current `main`)
## Framework Version
N/A
## Node.js Version
N/A
## OS
N/A
## Language
N/A
## Language Version
N/A
## Other information
The five consumers were located in `packages/aws-cdk/lib/cli/cli.ts` (reads of `argv.json` / `args.json`); the global declaration is in `packages/aws-cdk/lib/cli/cli-config.ts`.
Contributor guide
Research direction
Start with the global option declaration in packages/aws-cdk/lib/cli/cli-config.ts and the argv.json/args.json consumers in packages/aws-cdk/lib/cli/cli.ts. Review the per-command option definitions and the repository's backwards-compatibility policy before deciding how unsupported commands should behave. Regenerate the parser through @aws-cdk/user-input-gen and verify that supported commands retain JSON behavior while other commands no longer silently ignore the option.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- cli
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100