fix: suggest close CLI commands by glenn-agent · Pull Request #91345 · openclaw/openclaw

glenn-agent · 2026-06-08T07:01:38Z

Summary

add a small shared helper for close root-command suggestions using known CLI command metadata
suggest openclaw update for close typos such as upate and explicit adjacent terminology such as upgrade
wire suggestions into both Commander unknown-command output and the early unowned-root/plugin-policy path

Real behavior proof

Behavior or issue addressed: Unknown root commands should keep failing safely, but near misses should include a helpful Did you mean this? hint instead of only generic help text.
Real environment tested: Local OpenClaw checkout on Linux, Node v24.15.0, branch fix/83999-cli-command-suggestions after commit 96aa8d1714.
Exact steps or command run after this patch: Ran the focused CLI formatter and dispatch regression tests with node scripts/run-vitest.mjs src/cli/program/error-output.test.ts src/cli/run-main.exit.test.ts, plus git diff --check. I also ran a real source CLI smoke with Corepack's pnpm shim on PATH:

$ pnpm openclaw upate
[openclaw] Building TypeScript (dist is stale: missing_build_stamp - build stamp missing).
[openclaw] Building bundled plugin assets.
[canvas] build: node scripts/bundle-a2ui.mjs
<DIR>/a2ui.bundle.js  chunk │ size: 394.48 kB

✔ rolldown v1.1.0 Finished in 127.97 ms
[diffs] build: node ../../scripts/build-diffs-viewer-runtime.mjs curated
[diffs-language-pack] build: node ../../scripts/build-diffs-viewer-runtime.mjs full
runtime-postbuild: plugin SDK root alias completed in 0ms
runtime-postbuild: bundled plugin metadata completed in 315ms
runtime-postbuild: official channel catalog completed in 3ms
runtime-postbuild: bundled plugin runtime overlay completed in 133ms
runtime-postbuild: static extension assets completed in 55ms
runtime-postbuild: stable root runtime imports completed in 190ms
runtime-postbuild: stable root runtime aliases completed in 26ms
runtime-postbuild: legacy root runtime compat aliases completed in 4ms
runtime-postbuild: legacy CLI exit compat chunks completed in 0ms
[openclaw] Could not start the CLI.
[openclaw] Reason: Unknown command: openclaw upate. No built-in command or plugin CLI metadata owns "upate".
Did you mean this?
  openclaw update
[openclaw] Debug: set OPENCLAW_DEBUG=1 to include the stack trace.
[openclaw] Try: openclaw doctor
[openclaw] Help: openclaw --help
[ELIFECYCLE] Command failed with exit code 1.

(exit 1)

Evidence after fix: Copied live terminal output from the real source CLI smoke above showed the changed behavior after the fix:

[openclaw] Reason: Unknown command: openclaw upate. No built-in command or plugin CLI metadata owns "upate".
Did you mean this?
  openclaw update
[openclaw] Debug: set OPENCLAW_DEBUG=1 to include the stack trace.
[openclaw] Try: openclaw doctor
[openclaw] Help: openclaw --help
[ELIFECYCLE] Command failed with exit code 1.

(exit 1)

After the follow-up commit 96aa8d1714, copied local focused test output also verifies the plugin-policy guardrail remains separate from generic typo suggestions:

[test] starting test/vitest/vitest.unit-fast.config.ts
✓ unit-fast src/cli/run-main.test.ts (38 tests)

[test] starting test/vitest/vitest.cli.config.ts
✓ cli src/cli/program/error-output.test.ts (6 tests)
✓ cli src/cli/run-main.exit.test.ts (93 tests)

[test] passed 2 Vitest shards in 7.70s

Earlier terminal output from the after-fix focused test run:

[test] starting test/vitest/vitest.unit-fast.config.ts
✓ unit-fast src/cli/program/error-output.test.ts (5 tests)

[test] starting test/vitest/vitest.cli.config.ts
✓ cli src/cli/run-main.exit.test.ts (92 tests)

[test] passed 2 Vitest shards in 7.86s

The formatter test asserts this exact output for upate:

OpenClaw does not know the command "upate".
Did you mean this?
  openclaw update
Try: openclaw --help
Plugin command? openclaw plugins list
Docs: https://docs.openclaw.ai/cli

The dispatch test asserts the early unowned-root path rejects before proxy/plugin runtime startup while including:

Did you mean this?
  openclaw update

Observed result after fix: Close unknown root commands now include a closest-command suggestion while preserving the existing non-executing failure behavior and plugin-policy guardrails.
What was not tested: Full repository CI locally; GitHub Actions is running the broader matrix on the PR branch.

Tests

node scripts/run-vitest.mjs src/cli/program/error-output.test.ts src/cli/run-main.exit.test.ts
node scripts/run-vitest.mjs src/cli/program/error-output.test.ts src/cli/run-main.exit.test.ts src/cli/run-main.test.ts
git diff --check

clawsweeper · 2026-06-08T07:03:51Z

Codex review: passed. Reviewed June 19, 2026, 1:52 AM ET / 05:52 UTC.

Summary
The PR adds descriptor-backed CLI command suggestions for unknown root commands, wires them into Commander parse errors and early unowned-root diagnostics, and covers both paths with focused CLI tests.

PR surface: Source +104, Tests +71. Total +175 across 5 files.

Reproducibility: yes. for the behavior gap: current main's formatter and early unowned-root path emit generic diagnostics without closest-command hints, and the PR proof shows the after-fix CLI output.

Review metrics: none identified.

Stored data model
Persistent data-model change detected: migration/backfill/repair: src/cli/program/command-suggestions.ts, migration/backfill/repair: src/cli/program/error-output.test.ts, vector/embedding metadata: src/cli/run-main.ts. Migration or upgrade compatibility proof is recorded; maintainers should verify it before merge.

Root-cause cluster
Relationship: fixed_by_candidate
Canonical: #83999
Summary: The linked issue is the canonical request for closest-command CLI suggestions; this PR is the active fix candidate, while the earlier same-topic PR is closed unmerged.

Members:

canonical: feat(cli): suggest closest command for unknown subcommands #83999 - The issue describes the exact unknown-root command suggestion behavior and this PR uses closing syntax for it.
superseded: feat(cli): suggest closest command for unknown subcommands (#83999) #84036 - The older same-topic PR is closed unmerged and had weaker path coverage/proof than the current active PR.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦞 diamond lobster
Proof: 🦞 diamond lobster
Patch quality: 🦞 diamond lobster
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Next step before merge

[P2] No repair lane is needed; the remaining action is normal automerge or maintainer landing through exact-head gates.

Security
Cleared: The diff changes CLI diagnostic formatting and tests only; it adds no dependencies, workflows, package metadata, credential handling, or external code execution.

Review details

Best possible solution:

Land this focused helper through the active exact-head merge/check gates, then close the linked issue once main contains the suggestion behavior.

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

Yes for the behavior gap: current main's formatter and early unowned-root path emit generic diagnostics without closest-command hints, and the PR proof shows the after-fix CLI output.

Is this the best way to solve the issue?

Yes. A shared descriptor-backed helper covering both unknown-root surfaces is the narrow maintainable solution, and it avoids auto-running aliases or changing plugin-policy diagnostics.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 82ae81f3bf1d.

Label changes

Label changes:

add rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
add status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Sufficient (live_output): Copied after-fix terminal output from a real Linux source CLI invocation demonstrates the new suggestion and retained nonzero failure behavior.
remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦞 diamond lobster, so this older rating label is no longer current.
remove status: 👀 ready for maintainer look: Current PR status label is status: 🚀 automerge armed.

Label justifications:

P3: This is low-risk CLI recovery polish with limited blast radius, focused tests, and supplied real behavior proof.
rating: 🦞 diamond lobster: Overall readiness is 🦞 diamond lobster; proof is 🦞 diamond lobster and patch quality is 🦞 diamond lobster.
status: 🚀 automerge armed: This PR is in ClawSweeper's automerge lane. Sufficient (live_output): Copied after-fix terminal output from a real Linux source CLI invocation demonstrates the new suggestion and retained nonzero failure behavior.
proof: sufficient: Contributor real behavior proof is sufficient. Copied after-fix terminal output from a real Linux source CLI invocation demonstrates the new suggestion and retained nonzero failure behavior.

Evidence reviewed

PR surface:

Source +104, Tests +71. Total +175 across 5 files.

View PR surface stats

Area	Files	Added	Removed	Net
Source	3	108	4	+104
Tests	2	71	0	+71
Docs	0	0	0	0
Config	0	0	0	0
Generated	0	0	0	0
Other	0	0	0	0
Total	5	179	4	+175

What I checked:

Repository policy read: Root AGENTS.md was read fully and applied; no scoped AGENTS.md owns src/cli, so the root review, proof, current-main, and best-fix rules apply. (AGENTS.md:1, 82ae81f3bf1d)
Current main lacks Commander suggestions: Current main formats unknown Commander commands with the error, root help, plugin hint, and docs link only; there is no suggestion hook. (src/cli/program/error-output.ts:51, 82ae81f3bf1d)
Current main lacks early-root suggestions: Current main's early unowned-root diagnostic falls back to a generic unknown-command message after plugin-policy checks, also without a closest-command hint. (src/cli/run-main.ts:596, 82ae81f3bf1d)
Latest release lacks the behavior: The latest release tag v2026.6.8 has the same generic unknown-command formatter and no Did-you-mean suggestion line. (src/cli/program/error-output.ts:51, 844f405ac1be)
PR adds the shared suggestion helper: The proposed helper derives known commands from core and sub-CLI descriptors, applies explicit aliases, ranks close Levenshtein matches, and formats CLI suggestions with active command context. (src/cli/program/command-suggestions.ts:55, b98f5b59e6de)
PR covers both unknown-command paths: The merge-result diff adds the helper to Commander parse errors and to resolveUnownedCliPrimaryMessage after preserving plugin-policy diagnostics. (src/cli/run-main.ts:601, e48296ceafb4)

Likely related people:

vincentkoc: Current-main blame for the unknown-command formatter and early unowned-root diagnostic points to Vincent Koc, and live commit history shows recent CLI startup/parser work in the same path. (role: recent current-main CLI diagnostic contributor; confidence: high; commits: fb69db6365b2, 39250bbe655d, 042ebb4f75f3; files: src/cli/program/error-output.ts, src/cli/run-main.ts)
steipete: History over the CLI routing and descriptor surfaces shows repeated shared command metadata, registration, and startup-routing work that this helper reuses. (role: long-term CLI routing and descriptor contributor; confidence: high; commits: f43aba40a2c5, 5edabf4776c9, beaff3c553d9; files: src/cli/run-main.ts, src/cli/program/core-command-descriptors.ts, src/cli/program/subcli-descriptors.ts)
gumadeiras: Git history shows descriptor-backed lazy root command registration and root-help descriptor work on the same command catalogs used for suggestions. (role: adjacent descriptor-backed CLI contributor; confidence: medium; commits: 9b4f26e70af0, e5dac0c39e91; files: src/cli/program/core-command-descriptors.ts, src/cli/program/subcli-descriptors.ts, src/cli/run-main.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

ClawSweeper keeps one durable marker-backed review comment per issue or PR.
Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
Maintainers can also comment @clawsweeper review to request a fresh review only.
Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Signed-off-by: Glenn-Agent <[email protected]>

…-suggestions

glenn-agent · 2026-06-15T10:40:49Z

Follow-up pushed after review cleanup:

Removed the unrelated agent test fixture drift from the PR branch; the current branch diff against origin/main is scoped to the CLI command-suggestion files.
Reran focused CLI validation:
- git diff --check origin/main...HEAD
- node scripts/run-vitest.mjs src/cli/program/error-output.test.ts src/cli/run-main.exit.test.ts src/cli/run-main.test.ts — 137 tests passed
Reran affected agent regression checks after the branch cleanup:
- node scripts/run-vitest.mjs src/agents/anthropic-transport-stream.test.ts src/agents/simple-completion-runtime.test.ts — 85 tests passed

GitHub Actions is now running the broader PR matrix on the updated branch.

vincentkoc · 2026-06-19T05:42:40Z

/clownfish automerge

openclaw-clownfish · 2026-06-19T05:44:28Z

Clownfish is on the reef for this PR. 🐠

I tagged clownfish:automerge and sent ClawSweeper over this exact head. If the sweep finds rough coral, failing checks, or needs-human, I will take another bounded repair lap and ask for a fresh review.

A maintainer can call /clownfish stop any time and I will drift this back to human review.

clawsweeper · 2026-06-19T05:54:19Z

🦞✅
ClawSweeper merged this PR after the passing review.

Source: clawsweeper[bot]
Feedback: structured ClawSweeper verdict: pass (sha=b98f5b59e6de7d2947992645d97420cc1785f8fd)
Merge status: merged by ClawSweeper automerge
Merged at: 2026-06-19T05:54:15Z
Merge commit: 2f1275549816

What merged:

The PR adds descriptor-backed CLI command suggestions for unknown root commands, wires them into Commander parse errors and early unowned-root diagnostics, and covers both paths with focused CLI tests.
PR surface: Source +104, Tests +71. Total +175 across 5 files.
Reproducibility: yes. for the behavior gap: current main's formatter and early unowned-root path emit generic diagnostics without closest-command hints, and the PR proof shows the after-fix CLI output.

Automerge notes:

PR branch already contained follow-up commit before automerge: fix: suppress suggestions for plugin policy diagnostics
PR branch already contained follow-up commit before automerge: Merge remote-tracking branch 'origin/main' into fix/83999-cli-command…
PR branch already contained follow-up commit before automerge: test: align agent model expectations
PR branch already contained follow-up commit before automerge: test: restore unrelated agent test fixture

The automerge loop is complete.

Automerge progress:

2026-06-19 05:53:43 UTC review passed b98f5b59e6de (structured ClawSweeper verdict: pass (sha=b98f5b59e6de7d2947992645d97420cc1785f...)

2026-06-19 05:54:18 UTC merged b98f5b59e6de (merged by ClawSweeper automerge)

Summary: - The PR adds descriptor-backed CLI command suggestions for unknown root commands, wires them into Commander parse errors and early unowned-root diagnostics, and covers both paths with focused CLI tests. - PR surface: Source +104, Tests +71. Total +175 across 5 files. - Reproducibility: yes. for the behavior gap: current main's formatter and early unowned-root path emit generic diagnostics without closest-command hints, and the PR proof shows the after-fix CLI output. Automerge notes: - PR branch already contained follow-up commit before automerge: fix: suppress suggestions for plugin policy diagnostics - PR branch already contained follow-up commit before automerge: Merge remote-tracking branch 'origin/main' into fix/83999-cli-command… - PR branch already contained follow-up commit before automerge: test: align agent model expectations - PR branch already contained follow-up commit before automerge: test: restore unrelated agent test fixture Validation: - ClawSweeper review passed for head b98f5b5. - Required merge gates passed before the squash merge. Prepared head SHA: b98f5b5 Review: openclaw#91345 (comment) Co-authored-by: Glenn-Agent <[email protected]>

openclaw-barnacle Bot added cli CLI command changes size: S proof: supplied External PR includes structured after-fix real behavior proof. labels Jun 8, 2026

glenn-agent force-pushed the fix/83999-cli-command-suggestions branch from 514bf6b to ac79843 Compare June 8, 2026 07:08

fix: suggest close CLI commands

17baf7f

Signed-off-by: Glenn-Agent <[email protected]>

glenn-agent force-pushed the fix/83999-cli-command-suggestions branch from ac79843 to 17baf7f Compare June 9, 2026 07:24

openclaw-barnacle Bot added triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. and removed proof: supplied External PR includes structured after-fix real behavior proof. labels Jun 10, 2026

openclaw-barnacle Bot removed the triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. label Jun 10, 2026

fix: suppress suggestions for plugin policy diagnostics

96aa8d1

openclaw-barnacle Bot added the agents Agent runtime and tooling label Jun 11, 2026

glenn-agent added 2 commits June 12, 2026 09:35

test: restore unrelated agent test fixture

f3879a3

Merge remote-tracking branch 'origin/main' into fix/83999-cli-command…

b98f5b5

…-suggestions

clawsweeper Bot mentioned this pull request Jun 15, 2026

feat(cli): suggest closest command for unknown subcommands #83999

Closed

openclaw-barnacle Bot removed the agents Agent runtime and tooling label Jun 15, 2026

openclaw-clownfish Bot mentioned this pull request Jun 15, 2026

feat(cli): suggest closest command for unknown subcommands (#83999) #84036

Closed

openclaw-clownfish Bot added clownfish:automerge Maintainer opted this Clownfish PR into bounded ClawSweeper-reviewed automerge clawsweeper:automerge Maintainer opted this PR into bounded ClawSweeper-reviewed automerge labels Jun 19, 2026

clawsweeper Bot merged commit 2f12755 into openclaw:main Jun 19, 2026
219 of 232 checks passed

clawsweeper Bot mentioned this pull request Jun 19, 2026

test(perf): compare saved CLI startup benchmarks #94812

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: suggest close CLI commands#91345

fix: suggest close CLI commands#91345
clawsweeper[bot] merged 6 commits into
openclaw:mainfrom
glenn-agent:fix/83999-cli-command-suggestions

glenn-agent commented Jun 8, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 8, 2026 •

edited

Loading

Uh oh!

glenn-agent commented Jun 15, 2026

Uh oh!

vincentkoc commented Jun 19, 2026

Uh oh!

openclaw-clownfish Bot commented Jun 19, 2026

Uh oh!

Uh oh!

clawsweeper Bot commented Jun 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

glenn-agent commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Real behavior proof

Tests

Uh oh!

clawsweeper Bot commented Jun 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

glenn-agent commented Jun 15, 2026

Uh oh!

vincentkoc commented Jun 19, 2026

Uh oh!

openclaw-clownfish Bot commented Jun 19, 2026

Uh oh!

Uh oh!

clawsweeper Bot commented Jun 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

glenn-agent commented Jun 8, 2026 •

edited

Loading

clawsweeper Bot commented Jun 8, 2026 •

edited

Loading