feat(cli): default --output to text, reject conflicting flag combinations#51
Merged
Conversation
…ions
- Default --output changed from json to text for human-friendly interaction
- Added mutex checks: --quiet vs {-v, --debug}, and --resume vs --fresh
- Updated help text on -v, --debug, --quiet, --display for clarity
- Added test_argv_validation.py with 3 tests for mutex validation
- 6 test files updated to explicitly pass --output json (now required)
- All 637 tests pass (3 env-only skips)
- Wrapper contract preserved: wrappers always pass --output json explicitly
This is Phase 2 of docs/designs/2026-06-11-drop-xdg-and-flag-cleanup.md
Phase 1 (storage unification) shipped as PR #50.
BREAKING: Scripts relying on default --output json envelope will need to add
--output json explicitly. See PR body for wrapper contract guarantees.
Generated with [Amplifier](https://github.com/microsoft/amplifier)
Co-Authored-By: Amplifier <240397093+microsoft-amplifier@users.noreply.github.com>
This was referenced Jun 12, 2026
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
1 participant
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.
Motivation
Human-friendly defaults for CLI invocation, combined with safety checks to reject previously-silent flag conflicts.
What Changed
Phase 2.1: Default Output Mode
--outputdefault fromjsontotext(single_turn.py:521)--output jsonexplicitly, so no wrapper impactPhase 2.2: Mutex Flag Checks
--quietnow conflicts explicitly with-v/--verboseand--debug(previously silent last-wins)--resumeand--freshare now mutually exclusive (no check existed)click.UsageError(exit 2), consistent with existing-y/-nmutexPhase 2.3: Help Text Polish
-v,--debug,--quietnow note: "Only applies with --display text; ignored under --display ndjson"--displayclarified to govern stderr format independently of--output(stdout)Behavioral Break (Scripting Impact)
Scripts relying on the previous default
--output jsonenvelope WILL need updating to explicitly pass--output json. This is an intentional trade-off documented in the design doc (§"Risk Summary" row 5).Wrapper-contract guarantee: Wrappers are unaffected because:
--output json--output jsonWrapper-Contract Preservation
--output jsonremains a valid value (default change only)Tests
tests/cli/test_argv_validation.py(3 tests for mutex validation)--output jsonReference
This is Phase 2 of
docs/designs/2026-06-11-drop-xdg-and-flag-cleanup.md(CLI Flag Cleanup)Phase 1 (storage unification) shipped as PR #50
Deferred
Item 2.4 (flag name asymmetry: -y vs --yes) — deferred because it would break wrapper contract. Requires wrapper major version. Captured in design doc for future work.
Generated with Amplifier