PR #59489: fix(cli): subcommand --help shows placeholder text instead of real subcommand help

• Repository: openclaw/openclaw
• Author: rrrrrredy
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59489

Description (problem / solution / changelog)

Summary

• Problem: Running openclaw <cmd> <subcmd> --help on lazily-registered subcommands displayed placeholder/stub help text instead of the actual command description and options.
• Why it matters: Users relying on --help to discover CLI options saw useless output, degrading discoverability and DX.
• What changed: Called placeholder.helpOption(false) on lazily-registered placeholder commands so Commander does not intercept --help before the real command is loaded. The real subcommand's help is now shown correctly.
• What did NOT change (scope boundary): Eager-loaded commands are unaffected. No changes to option parsing or command logic.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #59449
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: Commander's lazy registration pattern creates a placeholder command that intercepts --help before the real command handler has a chance to register the actual help text.
• Missing detection / guardrail: No test verified --help output for lazily-registered subcommands.
• Prior context: Issue #59449.
• Why this regressed now: The lazy-registration pattern was introduced without accounting for --help interception.
• If unknown, what was ruled out:

Regression Test Plan (if applicable)

• Coverage level:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: N/A (manual verification only)
• Scenario the test should lock in: --help on lazily-registered subcommand shows real options.
• Why this is the smallest reliable guardrail: The fix is a one-liner; the risk surface is narrow.
• Existing test that already covers this: N/A
• If no new test is added, why not: Commander's help output is integration-level; unit testing it would require spawning a subprocess, disproportionate for a one-liner fix.

User-visible / Behavior Changes

openclaw <cmd> <subcmd> --help now shows the correct help text for lazily-registered commands.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Human Verification (required)

• Verified scenarios: openclaw cron add --help now shows correct options and description instead of placeholder text.
• Edge cases checked: Checked that eager-loaded commands still show correct help.
• What you did not verify: Help output on Windows terminal.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Problem

openclaw cron <subcommand> --help always showed the parent cron command's help text instead of the subcommand's actual help. For example:

$ openclaw cron add --help
# Output: cron command help (not cron add help)

Root Cause

The CLI registers subcommands lazily via placeholder Command objects. The placeholder commands had helpOption(false) disabled (inherited default), which caused Commander to silently swallow --help flags and fall through to the parent command's help handler.

Fix

Call .helpOption(false) explicitly on each placeholder command so that --help passes through to the real subcommand registration and is handled correctly.

Why helpOption(false) is safe: This only affects the placeholder command object, which is a temporary wrapper that exists solely to forward args to the real subcommand. The real subcommand's help option is unaffected. The parent program's -h/--help is also unaffected.

Why exitOverride on the root propagates to child commands: Commander v14's _exit() walks up the parent chain via this.parent._exit(), so exitOverride set on the root program is honored by all child commands including lazy-registered ones. This was verified against the Commander v14 source (copyInheritedSettings propagates _exitCallback).

Testing

Added regression test that verifies openclaw nodes list --help returns actual subcommand help output (not parent command placeholder text).

Related

Closes #59449

Changed files

• .github/actions/setup-node-env/action.yml (modified, +1/-1)
• .github/actions/setup-pnpm-store-cache/action.yml (modified, +1/-1)
• .github/labeler.yml (modified, +0/-27)
• .github/pr-assets/compaction-checkpoints/sessions-checkpoints-inline.png (removed, +0/-0)
• .github/pr-assets/compaction-checkpoints/sessions-overview-inline.png (removed, +0/-0)
• .github/pull_request_template.md (modified, +5/-3)
• .github/workflows/auto-response.yml (modified, +2/-6)
• .github/workflows/ci.yml (modified, +19/-2)
• .github/workflows/control-ui-locale-refresh.yml (removed, +0/-172)
• .github/workflows/docs-sync-publish.yml (removed, +0/-70)
• .github/workflows/docs-translate-trigger-release.yml (removed, +0/-42)
• .github/workflows/macos-release.yml (modified, +1/-1)
• .github/workflows/openclaw-npm-release.yml (modified, +9/-162)
• .github/workflows/plugin-clawhub-release.yml (removed, +0/-276)
• .github/workflows/plugin-npm-release.yml (modified, +1/-1)
• src/cli/program/register-lazy-command.ts (modified, +7/-0)
• src/cli/program/register.subclis.test.ts (modified, +32/-0)

PR #59501: fix(cli): pass --help through lazy command placeholders to subcommands

• Repository: openclaw/openclaw
• Author: miyago9267
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59501

Description (problem / solution / changelog)

Summary

• openclaw cron add --help (and all other lazy-registered subcommands) showed the parent command help instead of the subcommand's own help
• Root cause: Commander's built-in --help handler fires on the lazy placeholder before the action callback can re-register the real command tree
• Fix: placeholder.helpOption(false) lets --help pass through to the action, which removes the placeholder, registers the real subcommand tree, and re-parses — so the correct subcommand help is displayed

Affects all lazy-registered CLI commands (cron, nodes, dns, acp, channels, etc.), not just cron.

Fixes #59449

Test plan

• Added test: --help passes through placeholder and triggers real subcommand registration
• Existing tests pass (167 pass, 0 fail in src/cli/program/)
• Cron CLI tests pass (42 pass, 0 fail)
• Verified with isolated Commander script: without fix action reached: false, with fix action reached: true

Changed files

• src/cli/program/register-lazy-command.ts (modified, +1/-0)
• src/cli/program/register.subclis.test.ts (modified, +19/-0)

PR #2: CLI: show nested cron subcommand help on --help (#59449)

• Repository: YangManBOBO/openclaw
• Author: YangManBOBO
• State: closed | merged: False
• Link: https://github.com/YangManBOBO/openclaw/pull/2

Description (problem / solution / changelog)

Summary

修复 openclaw cron <subcommand> --help 总是显示父级 cron 帮助的问题 (#59449)。

What changed

• 让 CLI 命令树注册与 parseAsync() 使用同一份 argv（避免 profile/container 等 argv 归一化导致的嵌套 help 错配）。

Test plan

• pnpm test -- src/cli/program/build-program.test.ts src/cli/program/cron-subcommand-help.integration.test.ts src/cli/run-main.test.ts
• pnpm test -- src/cli/program.smoke.test.ts

Made with Cursor

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/cli/program/build-program.test.ts (modified, +8/-15)
• src/cli/program/build-program.ts (modified, +1/-2)
• src/cli/program/cron-subcommand-help.integration.test.ts (added, +47/-0)
• src/cli/run-main.ts (modified, +3/-3)

PR #59519: CLI: show nested cron subcommand help on --help (#59449)

• Repository: openclaw/openclaw
• Author: YangManBOBO
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59519

Description (problem / solution / changelog)

Summary

修复 openclaw cron <subcommand> --help 总是显示父级 cron 帮助的问题 (#59449)。

What changed

• 让 CLI 命令树注册与 parseAsync() 使用同一份 argv（避免 profile/container 等 argv 归一化导致的嵌套 help 错配）。

Test plan

• pnpm test -- src/cli/program/build-program.test.ts src/cli/program/cron-subcommand-help.integration.test.ts src/cli/run-main.test.ts
• pnpm test -- src/cli/program.smoke.test.ts

Changed files

• CHANGELOG.md (modified, +4/-0)
• src/cli/program/build-program.test.ts (modified, +8/-15)
• src/cli/program/build-program.ts (modified, +1/-2)
• src/cli/program/cron-subcommand-help.integration.test.ts (added, +47/-0)
• src/cli/run-main.ts (modified, +3/-3)