Context
Follow-up to #2102 / #2140.
Help-only discoverability ((c)) is done: top-level cli --help now points at tool-level --format json, and keeps payload JSON vs outer --json (MCP envelope) distinct.
In #2102, @DeusData noted that a session-wide flag or environment default needs a separate decision about supported tools and precedence, and that the help-only step did not approve that API extension. This issue is that decision request — discussion only; no PR until you say the shape is OK.
Proposal
Keep today’s defaults unchanged (including non-TTY: still no auto-switch to JSON).
- (a) Top-level flag:
cli [--format tree|json] <tool> ... as a default for tools that already accept format; an explicit per-tool --format still wins.
- (b) Env var:
CBM_CLI_FORMAT=tree|json for bridges that spawn the binary without full control over argv on every call.
I’d lean (a) + (b) if both are acceptable; either alone is also fine if you prefer a smaller surface.
Open questions for maintainers
- Supported tools — apply only where
format already exists today (search_graph / trace_path / detect_changes and any peers), or also refuse/warn when --format / CBM_CLI_FORMAT is set for a tool that has no format arg?
- Precedence — suggestion:
per-tool --format > top-level --format > CBM_CLI_FORMAT > built-in default (tree)
- Invalid values — hard error vs ignore-and-default for unknown
format / env values?
- Docs — top-level
CLI_USAGE + README CLI section only, or also each tool’s --help?
Non-goals
- Do not flip non-TTY stdout to JSON automatically.
- Do not change the meaning of outer
--json (full MCP envelope).
Happy to implement once you pick a direction (or say neither). Happy to adjust the precedence / tool set to match your preference.
Context
Follow-up to #2102 / #2140.
Help-only discoverability ((c)) is done: top-level
cli --helpnow points at tool-level--format json, and keeps payload JSON vs outer--json(MCP envelope) distinct.In #2102, @DeusData noted that a session-wide flag or environment default needs a separate decision about supported tools and precedence, and that the help-only step did not approve that API extension. This issue is that decision request — discussion only; no PR until you say the shape is OK.
Proposal
Keep today’s defaults unchanged (including non-TTY: still no auto-switch to JSON).
cli [--format tree|json] <tool> ...as a default for tools that already acceptformat; an explicit per-tool--formatstill wins.CBM_CLI_FORMAT=tree|jsonfor bridges that spawn the binary without full control over argv on every call.I’d lean (a) + (b) if both are acceptable; either alone is also fine if you prefer a smaller surface.
Open questions for maintainers
formatalready exists today (search_graph/trace_path/detect_changesand any peers), or also refuse/warn when--format/CBM_CLI_FORMATis set for a tool that has noformatarg?per-tool --format> top-level--format>CBM_CLI_FORMAT> built-in default (tree)format/ env values?CLI_USAGE+ README CLI section only, or also each tool’s--help?Non-goals
--json(full MCP envelope).Happy to implement once you pick a direction (or say neither). Happy to adjust the precedence / tool set to match your preference.