fix(cli): error on unknown command root when --help/--version is appended (#81077)

YB0y · YB0y · commit cc545c5a2524 · 2026-05-12T21:49:25.000+02:00
openclaw <unknown-command> --help silently fell through to generic top-level help and exited 0, while the same openclaw <unknown-command> (no --help) correctly errored with "Unknown command" and exited 1. The asymmetry was caused by two short-circuits on invocation.hasHelpOrVersion: resolveUnownedCliPrimary bailed before the unknown-primary check, and the only caller was gated on !isHelpOrVersionInvocation. Drop the hasHelpOrVersion bail in resolveUnownedCliPrimary so the helper continues to validate the primary when --help or --version is present, and add an unconditional caller in runCli after the root and browser help fast paths so legitimate help (openclaw --help, openclaw status --help, openclaw browser --help) still dispatches normally while unknown roots error consistently regardless of trailing flags. Verified: - pnpm test src/cli/run-main.exit.test.ts src/cli/argv.test.ts src/cli/argv-invocation.test.ts (76 passed) - pnpm exec oxfmt --check --threads=1 src/cli/run-main.ts src/cli/run-main.exit.test.ts (clean) - pnpm build && node openclaw.mjs heartbeat --help (exit 1, Unknown command error) - pnpm build && node openclaw.mjs status --help (exit 0, status help renders) - pnpm build && node openclaw.mjs browser --help (exit 0, browser help renders) - pnpm build && node openclaw.mjs --help (exit 0, root help renders) Closes #81077
diff --git a/src/cli/run-main.exit.test.ts b/src/cli/run-main.exit.test.ts
@@ -504,6 +504,26 @@ describe("runCli exit behavior", () => {
     expect(registerPluginCliCommandsFromValidatedConfigMock).not.toHaveBeenCalled();
   });
 
+  it("rejects unowned command roots even when --help is appended (regression for #81077)", async () => {
+    await expect(runCli(["node", "openclaw", "foo", "--help"])).rejects.toThrow(
+      'No built-in command or plugin CLI metadata owns "foo"',
+    );
+
+    expect(startProxyMock).not.toHaveBeenCalled();
+    expect(tryRouteCliMock).not.toHaveBeenCalled();
+    expect(buildProgramMock).not.toHaveBeenCalled();
+    expect(registerPluginCliCommandsFromValidatedConfigMock).not.toHaveBeenCalled();
+  });
+
+  it("rejects unowned command roots even when --version is appended", async () => {
+    await expect(runCli(["node", "openclaw", "foo", "--version"])).rejects.toThrow(
+      'No built-in command or plugin CLI metadata owns "foo"',
+    );
+
+    expect(startProxyMock).not.toHaveBeenCalled();
+    expect(tryRouteCliMock).not.toHaveBeenCalled();
+  });
+
   it("does not suggest plugins.allow for unknown command roots before proxy startup", async () => {
     loadConfigMock.mockReturnValueOnce({
       plugins: {
diff --git a/src/cli/run-main.ts b/src/cli/run-main.ts
@@ -367,7 +367,6 @@ async function resolveUnownedCliPrimary(params: {
   const invocation = resolveCliArgvInvocation(rewriteUpdateFlagArgv(params.argv));
   const { primary } = invocation;
   if (
-    invocation.hasHelpOrVersion ||
     !primary ||
     primary === "help" ||
     isReservedNonPluginCommandRoot(primary) ||
@@ -541,6 +540,19 @@ export async function runCli(argv: string[] = process.argv) {
       }
     }
 
+    // Reject unowned command roots before help/version routing, so that
+    // `openclaw <typo> --help` surfaces the same Unknown command error as
+    // `openclaw <typo>` instead of silently showing generic top-level help.
+    // Runs after the root and browser help fast paths so legitimate help still
+    // dispatches normally. See #81077.
+    {
+      const config = await readBestEffortCliConfig();
+      const unownedPrimary = await resolveUnownedCliPrimary({ argv: normalizedArgv, config });
+      if (unownedPrimary) {
+        throw new Error(await resolveUnownedCliPrimaryMessage({ primary: unownedPrimary, config }));
+      }
+    }
+
     const shouldRunBareRootCrestodian = shouldStartCrestodianForBareRoot(normalizedArgv);
     const shouldRunModernOnboardCrestodian = shouldStartCrestodianForModernOnboard(normalizedArgv);
     if (shouldRunBareRootCrestodian || shouldRunModernOnboardCrestodian) {
