Skip to content

Local code intelligence for developers and AI agents. Connect code, docs and infrastructure in a persistent graph, with CBM Lens, MCP tools, agent integrations and change-aware test selection.

feat(cli): point top-level cli --help at --format json

Lowpoweraaa72fbe60ad
diff --git a/src/cli/cli.h b/src/cli/cli.h
index cf7f6fa44..a1b749bb0 100644
--- a/src/cli/cli.h
+++ b/src/cli/cli.h
@@ -27,6 +27,18 @@ const char *cbm_cli_get_version(void);
/* ── CLI tool arguments (flags / --args-file / --help) ────────── */
+/* Top-level `cli --help` text printed by run_cli() in src/main.c.
+ * Documents tool-level --format without adding a session-wide flag (#2102). */
+#define CBM_CLI_USAGE \
+ "Usage: codebase-memory-mcp cli [--quiet] [--progress] [--verbose] [--json] <tool_name> " \
+ "[json_args]\n" \
+ " --quiet Show errors only; cannot combine with --progress or outer --verbose\n" \
+ " --progress Show lifecycle progress even when stderr is redirected\n" \
+ " --verbose Include informational logs (preserves CBM_LOG_LEVEL=debug)\n" \
+ " --json Print the raw MCP result envelope\n" \
+ " Tools that accept format support --format tree|json (default: tree).\n" \
+ " --format json prints payload JSON; outer --json prints the full MCP envelope.\n"
+
/* Convert `--flag value` / `--flag=value` / bare-boolean `--flag` arguments for
* a tool into a JSON arguments object string, using the tool's input_schema to
* type values (string/integer/boolean) and to collect repeated flags into
diff --git a/src/main.c b/src/main.c
index 9b91f205c..65e041217 100644
--- a/src/main.c
+++ b/src/main.c
@@ -675,13 +675,7 @@ static bool client_start_parent_watchdog(DWORD initial_ppid) {
/* ── CLI mode ───────────────────────────────────────────────────── */
-#define CLI_USAGE \
- "Usage: codebase-memory-mcp cli [--quiet] [--progress] [--verbose] [--json] <tool_name> " \
- "[json_args]\n" \
- " --quiet Show errors only; cannot combine with --progress or outer --verbose\n" \
- " --progress Show lifecycle progress even when stderr is redirected\n" \
- " --verbose Include informational logs (preserves CBM_LOG_LEVEL=debug)\n" \
- " --json Print the raw MCP result envelope\n"
+#define CLI_USAGE CBM_CLI_USAGE /* `cli --help`; wording lives in cli.h (#2102) */
/* Extract text content from MCP tool result envelope and print it.
* MCP results: {"content":[{"type":"text","text":"..."}],"isError":...}
diff --git a/tests/test_cli.c b/tests/test_cli.c
index 211ec6355..2ca51ab2f 100644
--- a/tests/test_cli.c
+++ b/tests/test_cli.c
@@ -15336,6 +15336,21 @@ TEST(cli_print_tool_help_issue680) {
PASS();
}
+/* #2102: top-level `cli --help` (CLI_USAGE) must point at tool-level
+ * `--format json` and distinguish it from outer `--json`. This is help-only:
+ * the usage synopsis still has no session-wide --format / CBM_CLI_FORMAT. */
+TEST(cli_usage_points_to_tool_format_json_issue2102) {
+ ASSERT_NOT_NULL(strstr(CBM_CLI_USAGE, "--format tree|json"));
+ ASSERT_NOT_NULL(strstr(CBM_CLI_USAGE, "payload JSON"));
+ ASSERT_NOT_NULL(strstr(CBM_CLI_USAGE, "full MCP envelope"));
+ ASSERT_NOT_NULL(strstr(CBM_CLI_USAGE, "--json Print the raw MCP result envelope"));
+ ASSERT_NOT_NULL(strstr(CBM_CLI_USAGE,
+ "cli [--quiet] [--progress] [--verbose] [--json] <tool_name>"));
+ ASSERT_NULL(strstr(CBM_CLI_USAGE, "[--format"));
+ ASSERT_NULL(strstr(CBM_CLI_USAGE, "CBM_CLI_FORMAT"));
+ PASS();
+}
+
/* #1359: `cli <tool>` with no argument-bearing token used to slurp stdin to EOF
* for ANY non-terminal stdin. The ordinary automation caller never sends that
* EOF — Node's child_process.spawn defaults to stdio:['pipe','pipe','pipe'] and
@@ -16376,6 +16391,7 @@ SUITE(cli) {
RUN_TEST(cli_build_args_json_key_equals_value_issue680);
RUN_TEST(cli_build_args_json_bad_positional_errors_issue680);
RUN_TEST(cli_print_tool_help_issue680);
+ RUN_TEST(cli_usage_points_to_tool_format_json_issue2102);
/* Stdin argument gate (#1359) */
RUN_TEST(cli_zero_argument_tool_never_reads_stdin_issue1359);