openclaw - 💡(How to fix) Fix [Bug]: `openclaw sessions list` is the only list-style parent command that rejects the `list` subcommand — misleading "Too many arguments" error, dead-end `--help` suggestion, and convention violation vs `cron list` / `commitments list` / `devices list` / `mcp list`

Bug type

Behavior bug (incorrect output/state without crash)

Beta release blocker

No

Summary

Every other "list-style" parent command in the CLI — cron, commitments, devices, mcp, plus plugins, agents, tasks, etc. — accepts a list subcommand and prints the list. sessions is the only outlier: it errors with Too many arguments for this command. and then suggests Try: openclaw sessions list --help. Both the error message and the suggestion are misleading:

1. Wrong diagnosis. The problem isn't "too many arguments" — it's that list is the natural-but-unrecognized subcommand. The actual sessions listing is the bare openclaw sessions call.
2. Dead-end suggestion. Following the suggested openclaw sessions list --help silently drops the list arg and prints help for bare sessions, so the user never learns that list isn't a real subcommand here.
3. Convention violation. Users coming from cron list, commitments list, devices list, mcp list reasonably expect sessions list to work.

Reproduces on v2026.5.10-beta.1 (today's npm beta) and v2026.5.7 (today's stable — the closed #60905 fix only addressed exit code, not the UX shape).

Steps to reproduce

1. On any current OpenClaw install (v2026.5.7 or v2026.5.10-beta.1).

2. Run:

   pnpm openclaw sessions list

3. Observe error: Too many arguments for this command. / Try: openclaw sessions list --help, exit 1.

4. Follow the suggestion: pnpm openclaw sessions list --help. Observe that it silently shows help for bare sessions (no list mentioned anywhere), exit 0.

5. Compare against any other list-style parent:

   pnpm openclaw cron list           # works, prints cron table
   pnpm openclaw commitments list    # works, prints commitments table
   pnpm openclaw devices list        # works, prints devices table
   pnpm openclaw mcp list            # works, prints MCP servers or "No MCP servers configured"

   All four produce normal list output. Only sessions list errors.

Expected behavior

Either of (in increasing scope):

1. Accept list as an alias for bare sessions. Smallest UX win — register list as a no-op alias subcommand on the sessions parent that just delegates to the same handler as the bare form. Matches cron/commitments/devices/mcp convention.
2. Fail with a more accurate error if list is genuinely not supported. Replace the misleading Too many arguments for this command. with The "sessions" command lists sessions directly — drop "list". Try: openclaw sessions (or similar). Fix the Try: suggestion to NOT point at sessions list --help, which only succeeds by silently dropping the extra arg.
3. Both. Accept list as an alias AND if any future cases reject extra positionals, give a precise error.

Today's behavior — error + a recovery suggestion that "works" only because help silently swallows the bad arg — is the worst of both worlds.

Actual behavior

Verbatim on v2026.5.10-beta.1 (152ea9af34):

$ openclaw sessions list
Too many arguments for this command.
Try: openclaw sessions list --help
[ELIFECYCLE] Command failed with exit code 1.

$ openclaw sessions list --help        # follow the recovery suggestion
🦞 OpenClaw 2026.5.10-beta.1 (152ea9a) — All your chats, one OpenClaw.

Usage: openclaw sessions [options] [command]
…
[exit 0]                # silently dropped "list" — user never sees that "list" isn't a real subcommand

Compare with the four other parent commands:

$ openclaw cron list
ID                                   Name                     Schedule                  Next       Last       …
ea71661c-b361-4dc5-b1e4-70195a00d62a Memory Dreaming Promo... cron 0 3 * * * (exact)    in 10h     14h ago    ok

$ openclaw commitments list
Commitments: 0
Store: /home/orin/.openclaw/commitments/commitments.json
…

$ openclaw devices list
Paired (3)
┌──────────────────┬────────────┬───…

$ openclaw mcp list
No MCP servers configured in /home/orin/.openclaw/openclaw.json. Add one with openclaw mcp set …

sessions is the only odd one out.

OpenClaw version

• v2026.5.10-beta.1 (today's npm beta, 9c7e67b0f8). Verified live.
• v2026.5.7 (today's npm stable). The closed #60905 fix landed before 2026.4.2 and only addressed exit code; the UX-shape defects all reproduce on v2026.5.7 too because the sessions command-registration code didn't add a list subcommand alias.

Operating system

Ubuntu 24.04 (Linux 6.8.0-110-generic). OS-agnostic — pure CLI command-registration UX.

Install method

pnpm openclaw … from source checkout. Reproduces on any install path.

Model

Not applicable — pure CLI dispatch defect.

Provider / routing chain

Not applicable.

Additional provider/model setup details

Not relevant. Reproduces on any config.

Logs, screenshots, and evidence

Full evidence log saved at qa-reports/12-sessions-list-ux-inconsistency/v2026.5.10-beta.1-evidence.log — comparison capture across all 5 parent commands.

Verifiable in two commands:

$ openclaw sessions list; echo "exit=$?"
Too many arguments for this command.
Try: openclaw sessions list --help
[ELIFECYCLE] Command failed with exit code 1.
exit=1

$ openclaw sessions list --help; echo "exit=$?"
…shows help for bare 'sessions' (silently drops 'list')…
exit=0

Impact and severity

• Affected: every user who tries sessions list after working with cron list / devices list / commitments list / mcp list — essentially every CLI user who's hit any other list-style parent first.
• Severity: Low. UX / discoverability bug. Not blocking. The bare openclaw sessions form still works.
• Frequency: 100% on openclaw sessions list.
• Concrete consequences:
  • Users hit the misleading "Too many arguments" error and follow the help suggestion, which silently drops list and shows them help that doesn't mention the actual cause. They might assume list is broken / hidden when in fact it doesn't exist on this parent.
  • Shell-completion / discovery scripts that probe <parent> list --help to enumerate listable subcommands get a false-positive exit-0 on sessions list --help, then later get an exit-1 on the actual sessions list invocation. Surprising and hard to debug.
  • Scripts that source from existing-issue closure assumptions (#60905 was closed implying "sessions list works now") get the wrong impression.

Why this isn't already fixed and isn't a duplicate

• Distinct from closed #60905 ("openclaw sessions list returns exit code 0 despite error output"). That issue was specifically about exit code — fixed (verified: sessions list now exits 1 via [ELIFECYCLE] Command failed with exit code 1.). My finding is the UX shape of the same defect path: error wording, recovery suggestion, and convention violation — none of which #60905's fix touched.
• Distinct from #77943 OPEN ("RFC: standardize --json envelope shape across list-style subcommands (agents/sessions/models/cron/nodes/skills)"). That's about JSON envelope shape across already-working list commands. My finding is about sessions list not being recognized at all.
• Distinct from #63118 OPEN ("Missing Session Management Commands in OpenClaw"). That's a feature request for new session-mgmt commands, not a fix to the existing sessions UX.
• Dedup search (open + closed): openclaw sessions list, sessions list "Too many arguments", openclaw sessions subcommand, CLI list convention sessions cron. No existing issue matches the convention-violation + misleading-error angle.

Suggested fix sketch

Two reasonable shapes:

1. Smallest: register a list subcommand alias on the sessions parent that just delegates to the same handler as the bare sessions form. This is exactly how commitments works (bare and commitments list both list the same thing). Mirrors the convention used by cron, devices, mcp. Probably 5-10 lines in the sessions CLI registration file.

2. Medium: fix the error message + the dead-end suggestion if alias is rejected. Replace Too many arguments for this command. with The "sessions" command lists sessions directly — drop "list" to list, or use "openclaw sessions cleanup" / "openclaw sessions export-trajectory" for the available subcommands. and stop suggesting openclaw sessions list --help (which silently drops the bad arg).

Both fixes are tiny. Option (1) is the user-friendly one; option (2) is a minimum-viable UX patch.

Regression test:

it("openclaw sessions list works (alias to bare sessions form)", async () => {
  const { stdout, exitCode } = await runCli(["sessions", "list"]);
  expect(exitCode).toBe(0);
  expect(stdout).toMatch(/Session store:|Sessions listed:/);
});