Repository navigation
feat(cli): session-wide format default (top-level --format / CBM_CLI_FORMAT) — follow-up from #2102 #2298
Description
Context
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 acceptformat; an explicit per-tool--formatstill wins. - (b) Env var:
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
- Supported tools — apply only where
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? - 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.
Activity
DeusData commentedon Oct 19, 2026
Thank you for keeping the session-wide format proposal separate from the help-only change. Supported tools, precedence, invalid values, and documentation remain explicit direction questions; I have no new API approval to give yet.
Lowpower commentedon Oct 20, 2026
Thanks for the clarification — proposing concrete defaults so you can approve/reject by point. Still discussion-only; no PR until you say the shape is OK.
Surface: both (a) top-level
cli [--format tree|json] <tool> ...and (b)CBM_CLI_FORMAT=tree|json, unless you prefer only one.formattoday (search_graph/trace_path/detect_changesand any peers). If top-level--format/CBM_CLI_FORMATis set for a tool withoutformat, ignore those defaults (no warn/error); the tool keeps its current behavior.per-tool --format> top-level--format>CBM_CLI_FORMAT> built-in default (tree).--formatorCBM_CLI_FORMAT(same spirit as rejecting bad per-tool--format), with a short message listingtree|json.CLI_USAGE+ README CLI section only (point at the new defaults and the precedence). No change to each tool’s--helpbeyond what already documents per-tool--format.Non-goals (unchanged): no non-TTY auto-JSON; outer
--jsonstays the MCP envelope.If this shape looks right, I’m happy to open a focused PR. Happy to drop (a) or (b), or switch invalid values to ignore-and-default, if you prefer smaller surface.
DeusData commentedon Oct 25, 2026
Thank you for spelling out the defaults, precedence, and invalid-value behavior. Those concrete choices still need a maintainer decision before you open a PR. Sorry for the delay; I’ll follow up soon.