Skip to content

fix(cli): show the usage for lobster help run, resume, doctor and version - #218

Merged
steipete merged 2 commits into
openclaw:mainfrom
KrasimirKralev:improve/help-topics
Nov 14, 2026
Merged

steipete merged 2 commits into
openclaw:mainfrom
KrasimirKralev:improve/help-topics

Conversation

@KrasimirKralev

Copy link
Copy Markdown
Contributor

What Problem This Solves

lobster help run, lobster help resume, lobster help doctor and lobster help version fail with Unknown command: <name> (exit code 2), although lobster --help lists lobster run …, lobster resume …, lobster doctor and lobster version in its Usage block, directly above the lobster help <command> hint.

  • lobster help <topic> resolves graph (since fix(cli): show graph help for lobster help graph #212) and then only the pipeline command registry. run, resume, doctor, version and help are top-level CLI commands dispatched before the registry, so help reports them as unknown, which reads as if the command did not exist.
  • These commands have no dedicated help text: lobster run --help (and resume --help, doctor --help, version --help) already prints the top-level usage, which is where they are documented.
  • Scope: the help branch in src/cli.ts now prints that same top-level usage for these five topics. Registry commands, help graph, unknown topics (still Unknown command: <topic>, exit 2) and every --help path are unchanged.

User Impact

Someone who sees lobster run … in the usage and follows the lobster help <command> hint for it now gets the usage that documents run (its --mode, --file, --args-json and --dry-run forms) with exit 0, instead of an error saying the command is unknown. Scripts that call lobster help run no longer get exit code 2.

Why This Change Was Made

  • What changed: a USAGE_TOPICS set (run, resume, doctor, version, help) checked in the help branch after graph and before the registry lookup; it writes the existing helpText(), so help <topic> and <topic> --help print identical text.
  • Root cause: the top-level commands are dispatched by argv[0] before the registry, so they have no registry entry, but the help branch only consulted the registry (plus graph).
  • Missing detection: fix(cli): show graph help for lobster help graph #212 covered help graph only. New cases in test/cli_run_errors.test.ts run bin/lobster.js help <topic> for each of the five topics and check exit 0, an empty stderr, the lobster <topic> usage line, and that stdout equals bin/lobster.js <topic> --help; one more case pins that help nope still exits 2 with Unknown command: nope.
  • Regression check: with the new branch disabled, the full suite fails exactly the 5 new topic cases (744/749); with it, 749/749 pass.
  • A CHANGELOG line under ## Unreleased.

Evidence

  • Behavior or issue addressed: lobster help <top-level command> output and exit code.
  • Real environment tested: Linux, Node 24, lobster built from source (pnpm build) on upstream/main c19d3cf and on this branch.
  • Exact steps or command run after this patch: node bin/lobster.js help run|resume|doctor|version|nope and node bin/lobster.js run --help, before and after, plus pnpm lint, pnpm typecheck, pnpm test.
  • Evidence after fix:
# before (main c19d3cf)
$ node bin/lobster.js help run       -> exit 2: Unknown command: run
$ node bin/lobster.js help resume    -> exit 2: Unknown command: resume
$ node bin/lobster.js help doctor    -> exit 2: Unknown command: doctor
$ node bin/lobster.js help version   -> exit 2: Unknown command: version
$ node bin/lobster.js help nope      -> exit 2: Unknown command: nope
$ node bin/lobster.js run --help     -> exit 0: lobster — OpenClaw-native typed shell

# after (this branch)
$ node bin/lobster.js help run       -> exit 0: lobster — OpenClaw-native typed shell
$ node bin/lobster.js help resume    -> exit 0: lobster — OpenClaw-native typed shell
$ node bin/lobster.js help doctor    -> exit 0: lobster — OpenClaw-native typed shell
$ node bin/lobster.js help version   -> exit 0: lobster — OpenClaw-native typed shell
$ node bin/lobster.js help nope      -> exit 2: Unknown command: nope
$ node bin/lobster.js run --help     -> exit 0: lobster — OpenClaw-native typed shell

$ node bin/lobster.js help run | head -4
lobster — OpenClaw-native typed shell

Usage:
  lobster '<pipeline>'

$ pnpm test
ℹ tests 749
ℹ pass 749
ℹ fail 0
  • Observed result after fix: help for each top-level command prints the same usage as <command> --help and exits 0; an unknown topic still prints Unknown command and exits 2. pnpm lint and pnpm typecheck are clean.
  • What was not tested: no dedicated per-command help text is added; these topics print the shared top-level usage, as their --help already does.
  • Proof limitations or environment constraints: none.

@clawsweeper

clawsweeper Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Nov 10, 2026 •

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-14T08:25:38.040130Z 558e11e New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@clawsweeper clawsweeper Bot added clawsweeper:intake:bug Preliminary submission classification; full source review pending. P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed clawsweeper:intake:bug Preliminary submission classification; full source review pending. labels Nov 10, 2026
@clawsweeper

clawsweeper Bot commented Nov 10, 2026

Copy link
Copy Markdown

Codex review: needs maintainer review before merge.

What this changes

Make help for run, resume, doctor, version, and help print the existing top-level usage.

Example: Run lobster help run.

  • Before: Prints Unknown command: run and exits 2.
  • After: Prints the existing usage documenting run and exits 0.

Review scores

Measure Result What it means
Overall readiness 🦞 diamond lobster (5/6) A focused, useful repair with shipped CLI proof, relevant regression coverage, passing exact-head checks, and no findings.
Proof confidence 🦞 diamond lobster (5/6) Sufficient (terminal): The supplied terminal output exercises bin/lobster.js on built Linux Node 24 main and patched checkouts, showing the affected help topics change from exit 2 to usage output with exit 0 while an unknown topic still fails.
Patch quality 🦞 diamond lobster (5/6) No actionable review findings were identified.

Product

Kind: Bug fix · Worth it: Yes · Fix scope: Complete
User problem: Following the advertised help syntax for built-in commands incorrectly reports that those commands are unknown.
Reason: The change restores a documented help contract without adding a public API, setting, or new help format.

Merge readiness

✅ Ready for maintainer review

This PR fixes a current help-routing bug with a small, focused change; the supplied CLI evidence is sufficient, and no actionable defects were found.

Priority: P3
Reviewed head: 0de5d7930a26f8fe1f5d8204304ca89ba2232ea8

Before merge

None.

Findings

None.

Agent review details

How this fits together

The CLI receives command-line arguments, routes help topics to existing renderers or registry commands, and writes help or errors with an exit status.

flowchart TD
  A[CLI arguments] --> B[Help dispatcher]
  B --> C[Built-in usage topics]
  B --> D[Graph help]
  B --> E[Command registry]
  C --> F[Standard output]
  D --> F
  E --> F
Loading

Technical review

Best possible solution:

Land the focused routing fix using the existing usage renderer and CLI regression coverage.

Do we have a high-confidence way to reproduce the issue?

Current-main dispatch and registry contents establish the failure, corroborated by the contributor's before/after CLI output; no target code was executed during review.

Is this the best way to solve the issue?

Reusing the existing renderer in the existing help dispatcher is the smallest complete fix and preserves specialized graph and registry help.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against c19d3cf481e9.

Provenance checked

  • CLI help dispatch keeps the original intent (205f666: The original CLI resolved command help through its pipeline registry; the later merged graph repair established routing built-in topics to their existing renderer.)

Testing

Proof path: shipped entry point.

Security

None.

Evidence

What I checked:

  • Current-main defect: Main handles graph specially, then resolves every other help topic through the registry, which contains none of the five affected built-ins. (src/cli.ts:51, c19d3cf481e9)
  • Focused implementation: The introduced branch reuses helpText without changing graph routing, registry help, unknown-topic errors, or command execution. (src/cli.ts:54, 0de5d7930a26)
  • Shipped CLI proof: The full PR body supplies Linux Node 24 before/after output through bin/lobster.js for run, resume, doctor, and version help, preserving the unknown-topic failure; it also reports five baseline test failures and 749 passing tests after the change. (0de5d7930a26)
  • Prior help-routing repair: fix(cli): show graph help for lobster help graph #212 merged the analogous graph-topic repair and explicitly left other top-level topics unchanged; it does not implement this PR's fix. (src/cli.ts:49, 588cad4512de)
  • Exact-head checks: Node 22 and Node 24 checks, workflow lint, and dispatch passed at the reviewed head; one additional dispatch check was skipped. (0de5d7930a26)
  • Policy and inspection limits: Read the complete root AGENTS.md; no nested policies, maintainer notes, or pr-simplify skill were present. One historical git show encountered an unavailable old object; current source, relevant help history, and the original CLI blob were readable. The checkout remains clean. (AGENTS.md:1, 0de5d7930a26)

Likely related people:

  • Krasimir Kralev: Raw commit 588cad4 adds src/cli.ts:47 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 588cad4512de; files: src/cli.ts)
  • Peter Steinberger: Raw commit f9da0f1 adds src/cli.ts:31 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: f9da0f10eada; files: src/cli.ts)
  • Vignesh Natarajan: Raw commit 205f666 adds src/cli.js:60 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: medium; commits: 205f666ee021; files: src/cli.js)

Preflight source

Source unknown. Source comparison at the observed PR snapshot only. Completion is self-reported; body, policy, tests, execution, and report bytes are not verified.

Review metrics

Metric Value Why it matters
Change size Production +7, tests +23, changelog +2; no deletions The small routing addition is supported by CLI coverage for all five topics and an unknown-topic control.

Labels

Label changes:

  • add P3: Help discoverability is broken, while the existing command --help path remains available.
  • add proof: sufficient: Contributor real behavior proof is sufficient.
  • add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

  • P3: Help discoverability is broken, while the existing command --help path remains available.
  • rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.
  • proof: sufficient: Contributor real behavior proof is sufficient.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed November 10, 2026, 3:59 AM ET / 08:59 UTC.

@steipete
steipete merged commit d296ac2 into openclaw:main Nov 14, 2026
4 checks passed
@steipete

Copy link
Copy Markdown
Contributor

Merged in d296ac2. Reproduced the baseline built CLI reporting Unknown command for help run; the corrected built CLI prints usage successfully. Regression cases cover run, resume, doctor, version, help, and preservation of unknown-topic errors.

Validation: Linux Node 24 build, CLI smoke, lint, typecheck, and all 752 tests passed. Refreshed Node 22 and Node 24 CI passed at 558e11e: https://github.com/openclaw/lobster/actions/runs/43575592730. Independent review found no actionable P0–P2 findings. Thanks @KrasimirKralev.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

P3 Low-risk cleanup, docs, polish, ergonomics, or speculative feature. proof: sufficient Contributor real behavior proof is sufficient. rating: 🦞 diamond lobster Very strong PR readiness with only minor maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants