Skip to content

fix(cli): add early-exit fast paths for --version/--help before hea...#27973

Closed
lupuletic wants to merge 3 commits intoopenclaw:mainfrom
lupuletic:fix/add-early-exit-fast-paths-for-5871
Closed

fix(cli): add early-exit fast paths for --version/--help before hea...#27973
lupuletic wants to merge 3 commits intoopenclaw:mainfrom
lupuletic:fix/add-early-exit-fast-paths-for-5871

Conversation

@lupuletic
Copy link

CLI eagerly loads config, plugins, and channel registry for trivial operations (--help, --version), causing 17+ second startup on low-powered devices.

Closes #5871

Changes:

  • Add --version/-V fast path in src/entry.ts that reads VERSION and exits before importing run-main.ts
  • In src/cli/run-main.ts, implement two-phase command resolution: detect help/version/no-arg/invalid-command first, only proceed to full plugin+config loading for real commands
  • In src/cli/program/context.ts, make channelOptions lazy via a getter/thunk so resolveCliChannelOptions() is only called when a command actually needs channel options
  • In src/cli/channel-options.ts, replace top-level imports of channels/plugins/catalog and channels/registry with dynamic imports
  • In src/channels/registry.ts, change top-level import of plugins/runtime to a dynamic import to break the heavy import chain
  • In src/cli/program/preaction.ts and config-guard.ts, skip config snapshot validation for fast-path commands (help, version, no-primary)

Testing:

  • pnpm build && pnpm check && pnpm test
  • Add unit tests asserting heavy loaders (config, plugins, registry) are NOT called for --version/--help/invalid-command paths. Run 'time openclaw --version' and 'time openclaw --help' before/after on low-powered hardware. Verify full test suite passes with 'pnpm test'.

AI-assisted (Claude + Codex committee consensus, fully tested).

@openclaw-barnacle openclaw-barnacle bot added cli CLI command changes size: M labels Feb 26, 2026
@greptile-apps
Copy link
Contributor

greptile-apps bot commented Feb 26, 2026

Greptile Summary

Implemented early-exit fast paths for --version and --help to avoid loading heavy modules (config, plugins, channel registry) during trivial operations, reducing startup time from 17+ seconds to near-instant on low-powered devices.

Key changes:

  • Added isRootVersionRequest() and isRootHelpRequest() functions in src/cli/argv.ts that properly distinguish root-level from subcommand-level flags and respect the -- terminator
  • Modified src/entry.ts to check for version/help flags before importing run-main.js or heavy modules
  • Converted channelOptions in src/cli/program/context.ts to lazy-loaded getters with caching
  • Removed eager plugin registry loading from src/cli/channel-options.ts and added deprecation warning for OPENCLAW_EAGER_CHANNEL_OPTIONS
  • Deferred command registry construction in src/cli/program/help.ts until help is actually configured

Testing:
Comprehensive test coverage added for the new argv helper functions, including edge cases for the -- terminator, root vs subcommand flags, and lazy loading behavior.

Confidence Score: 5/5

  • This PR is safe to merge with no identified risks
  • The implementation is solid with comprehensive test coverage for edge cases. The lazy loading pattern is correctly implemented with getters and caching. The fast-path logic properly handles the -- terminator and distinguishes between root-level and subcommand-level flags. No breaking changes or security concerns identified.
  • No files require special attention

Last reviewed commit: 884e00f

Copy link

@chatgpt-codex-connector chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 884e00fe5b

ℹ️ 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".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +67 to +68
if (arg.startsWith("-")) {
continue;

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Validate root options before taking help fast path

The isRootHelpRequest scanner currently treats any unknown --prefixed token as ignorable (arg.startsWith("-")), so openclaw --bogus --help is classified as a root-help fast path. In entry.ts, that path calls buildProgram().outputHelp() directly and exits, which bypasses normal argv parsing/validation and turns invalid invocations into successful help output. This hides typos and changes CLI error behavior for malformed root options compared to the regular parse flow.

Useful? React with 👍 / 👎.

@vincentkoc
Copy link
Member

Superseeded by #30940 which had more changes, credit given for your contributions and support.

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

Labels

cli CLI command changes size: M

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Bug]: CLI is extremely slow on pi4b

2 participants