Merge pull request #2140 from Lowpower/cursor/cli-help-format-json-cb65

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

Author: DeusData

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

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":...}

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);