Skip to content

feat(cli): session-wide format default (top-level --format / CBM_CLI_FORMAT) — follow-up from #2102 #2298

Description

@Lowpower

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

  1. 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?
  2. Precedence — suggestion:
    per-tool --format > top-level --format > CBM_CLI_FORMAT > built-in default (tree)
  3. Invalid values — hard error vs ignore-and-default for unknown format / env values?
  4. 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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    parsing/qualityGraph extraction bugs, false positives, missing edges

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions