fix(cli): add sessions list alias matching cron/commitments/devices/mcp convention (#81139)

YB0y · YB0y · commit 9eff42fa04ad · 2026-05-12T22:58:42.000+02:00
openclaw sessions was the only list-style parent command that rejected a list subcommand. Every sibling (cron list, commitments list, devices list, mcp list, plugins list, agents list, tasks list) accepts the convention; sessions list errored with "Too many arguments for this command." and pointed users at openclaw sessions list --help, which silently dropped the list arg and showed help for bare sessions. The closed #60905 fix only addressed exit code, not the missing alias. Register sessionsCmd.command("list") that delegates to the same sessionsCommand handler the bare command already calls. With enablePositionalOptions on the parent, commander captures any option whose name matches the parent (--json, --verbose, --store, --agent, --all-agents, --active, --limit) onto the parent regardless of position, so the action merges its own opts with command.parent.opts(). Flags work both before and after list (sessions --json list and sessions list --json). Mirrors the parentOpts pattern already used by the sibling cleanup subcommand and by commitments list / tasks list elsewhere in this file. Verified: - pnpm test src/cli/program/register.status-health-sessions.test.ts (28 passed) - pnpm exec oxfmt --check --threads=1 src/cli/program/register.status-health-sessions.ts src/cli/program/register.status-health-sessions.test.ts (clean) - pnpm check:changed (exit 0) - pnpm build && node openclaw.mjs sessions list (lists sessions, exit 0) - pnpm build && node openclaw.mjs sessions list --json (JSON output, exit 0) - pnpm build && node openclaw.mjs sessions --json list (JSON output, exit 0) - pnpm build && node openclaw.mjs sessions list --agent work (forwards --agent, errors with "Unknown agent id 'work'") - pnpm build && node openclaw.mjs sessions --json (bare baseline unchanged, exit 0) - pnpm build && node openclaw.mjs sessions cleanup --dry-run (sibling subcommand unchanged, exit 0) Closes #81139
diff --git a/src/cli/program/register.status-health-sessions.test.ts b/src/cli/program/register.status-health-sessions.test.ts
@@ -241,6 +241,98 @@ describe("registerStatusHealthSessionsCommands", () => {
     });
   });
 
+  it("dispatches sessions list as an alias for bare sessions (regression for #81139)", async () => {
+    await runCli(["sessions", "list"]);
+
+    expect(sessionsCommand).toHaveBeenCalledTimes(1);
+    expectCommandOptions(sessionsCommand, {
+      json: false,
+      allAgents: false,
+      agent: undefined,
+      store: undefined,
+    });
+  });
+
+  it("forwards sessions parent options through the list alias (flags before list)", async () => {
+    await runCli([
+      "sessions",
+      "--json",
+      "--verbose",
+      "--store",
+      "/tmp/sessions.json",
+      "--active",
+      "120",
+      "--limit",
+      "25",
+      "list",
+    ]);
+
+    expect(setVerbose).toHaveBeenCalledWith(true);
+    expectCommandOptions(sessionsCommand, {
+      json: true,
+      store: "/tmp/sessions.json",
+      active: "120",
+      limit: "25",
+    });
+  });
+
+  it("forwards sessions list-side options (flags after list)", async () => {
+    await runCli([
+      "sessions",
+      "list",
+      "--json",
+      "--verbose",
+      "--store",
+      "/tmp/sessions.json",
+      "--active",
+      "120",
+      "--limit",
+      "25",
+    ]);
+
+    expect(setVerbose).toHaveBeenCalledWith(true);
+    expectCommandOptions(sessionsCommand, {
+      json: true,
+      store: "/tmp/sessions.json",
+      active: "120",
+      limit: "25",
+    });
+  });
+
+  it("forwards --agent through the list alias (flag before list)", async () => {
+    await runCli(["sessions", "--agent", "work", "list"]);
+
+    expectCommandOptions(sessionsCommand, {
+      agent: "work",
+      allAgents: false,
+    });
+  });
+
+  it("forwards --agent through the list alias (flag after list)", async () => {
+    await runCli(["sessions", "list", "--agent", "work"]);
+
+    expectCommandOptions(sessionsCommand, {
+      agent: "work",
+      allAgents: false,
+    });
+  });
+
+  it("forwards --all-agents through the list alias (flag before list)", async () => {
+    await runCli(["sessions", "--all-agents", "list"]);
+
+    expectCommandOptions(sessionsCommand, {
+      allAgents: true,
+    });
+  });
+
+  it("forwards --all-agents through the list alias (flag after list)", async () => {
+    await runCli(["sessions", "list", "--all-agents"]);
+
+    expectCommandOptions(sessionsCommand, {
+      allAgents: true,
+    });
+  });
+
   it("runs sessions cleanup subcommand with forwarded options", async () => {
     await runCli([
       "sessions",
diff --git a/src/cli/program/register.status-health-sessions.ts b/src/cli/program/register.status-health-sessions.ts
@@ -169,6 +169,54 @@ export function registerStatusHealthSessionsCommands(program: Command) {
     });
   sessionsCmd.enablePositionalOptions();
 
+  // Backward-compatible `sessions list` alias. Every other list-style parent
+  // command (cron, commitments, devices, mcp, plugins, agents, tasks) accepts
+  // a bare `list` subcommand; without this alias, `openclaw sessions list`
+  // hits the generic parser's "Too many arguments" path and the recovery
+  // suggestion (`sessions list --help`) silently drops the extra argument.
+  // See #81139.
+  //
+  // The action merges its own `opts` with `command.parent.opts()` so flags
+  // work both before and after `list` (e.g. `sessions --json list` and
+  // `sessions list --json`). This matches the parentOpts pattern used by the
+  // sibling `cleanup` subcommand below and by `commitments list` / `tasks
+  // list` elsewhere in this file.
+  sessionsCmd
+    .command("list")
+    .description("List stored conversation sessions (alias for `openclaw sessions`)")
+    .option("--json", "Output as JSON", false)
+    .option("--verbose", "Verbose logging", false)
+    .option("--store <path>", "Path to session store (default: resolved from config)")
+    .option("--agent <id>", "Agent id to inspect (default: configured default agent)")
+    .option("--all-agents", "Aggregate sessions across all configured agents", false)
+    .option("--active <minutes>", "Only show sessions updated within the past N minutes")
+    .option("--limit <count>", 'Max sessions to show (default: 100; use "all" for full output)')
+    .action(async (opts, command) => {
+      const parentOpts = command.parent?.opts() as
+        | {
+            json?: boolean;
+            verbose?: boolean;
+            store?: string;
+            agent?: string;
+            allAgents?: boolean;
+            active?: string;
+            limit?: string;
+          }
+        | undefined;
+      setVerbose(Boolean(opts.verbose || parentOpts?.verbose));
+      await sessionsCommand(
+        {
+          json: Boolean(opts.json || parentOpts?.json),
+          store: (opts.store as string | undefined) ?? parentOpts?.store,
+          agent: (opts.agent as string | undefined) ?? parentOpts?.agent,
+          allAgents: Boolean(opts.allAgents || parentOpts?.allAgents),
+          active: (opts.active as string | undefined) ?? parentOpts?.active,
+          limit: (opts.limit as string | undefined) ?? parentOpts?.limit,
+        },
+        defaultRuntime,
+      );
+    });
+
   sessionsCmd
     .command("cleanup")
     .description("Run session-store maintenance now")
