aws / aws/aws-cdk-cli

(cli): --json is a global option but is silently ignored by most commands

Open
#1,695 0 comments 0 reactions 0 assignees View on GitHub
bug p2
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.