Implementation:Openclaw Openclaw RunCli
| Knowledge Sources | |
|---|---|
| Domains | CLI, Bootstrap, Configuration |
| Last Updated | 2026-02-06 12:00 GMT |
Overview
Concrete entry point for bootstrapping the OpenClaw CLI, provided by the runCli function in src/cli/run-main.ts.
Description
runCli is the top-level async function that initializes the entire OpenClaw command-line interface. When invoked (typically from the package bin entry point), it performs environment setup (loading .env via dotenv, normalizing environment variables, ensuring the openclaw binary is on PATH), validates the runtime version, attempts fast-path CLI routing, and falls back to building the full Commander.js program tree with lazy subcommand registration and plugin command discovery.
The function also installs global error handlers for uncaughtException and unhandledRejection events, and enables structured console capture so that all output is routed through the logging subsystem. A companion helper, rewriteUpdateFlagArgv, transforms the --update flag into the update subcommand before parsing.
Usage
runCli is the main entry point of the openclaw CLI binary. It is called once at process startup. Application code should not call it directly except in the bin entry script or in integration tests that simulate full CLI invocations.
Code Reference
Source Location
- Repository: openclaw
- File:
src/cli/run-main.ts - Lines: 27-72
Signature
export async function runCli(argv: string[] = process.argv): Promise<void>
Import
import { runCli } from "../cli/run-main.js";
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| argv | string[] |
No (defaults to process.argv) |
The raw argument vector to parse. On Windows, duplicate node.exe entries are stripped automatically via stripWindowsNodeExec. |
Outputs
| Name | Type | Description |
|---|---|---|
| (return) | Promise<void> |
Resolves when the dispatched subcommand completes. On fatal errors, the process exits via the installed uncaughtException handler. |
Internal Flow
- Normalize argv -- strips Windows node.exe duplicates via stripWindowsNodeExec.
- Load environment -- calls loadDotEnv({ quiet: true }), normalizeEnv(), and ensureOpenClawCliOnPath().
- Assert runtime -- assertSupportedRuntime() throws if the Node/Bun version is below the minimum.
- Fast-path routing -- tryRouteCli(normalizedArgv) checks if the command can be dispatched directly (e.g., a native binary). If it returns true, the function exits early.
- Console capture -- enableConsoleCapture() intercepts stdout/stderr for structured logging.
- Build program -- dynamically imports ./program.js and calls buildProgram() to create the Commander.js Command instance.
- Error handlers -- installs installUnhandledRejectionHandler() and a process.on("uncaughtException") listener.
- Rewrite argv -- rewriteUpdateFlagArgv converts --update to update subcommand position.
- Lazy subcommand registration -- getPrimaryCommand identifies the subcommand from argv; if found, registerSubCliByName imports and registers only that subcommand.
- Plugin commands -- unless the invocation is a bare --help or --version, registerPluginCliCommands discovers and registers plugin-provided commands from the loaded config.
- Parse and dispatch -- program.parseAsync(parseArgv) invokes the matched Commander.js action handler.
Usage Examples
Basic Usage
// Bin entry point (src/cli/bin.ts)
import { runCli, isCliMainModule } from "./run-main.js";
if (isCliMainModule()) {
await runCli();
}
Testing with Custom Argv
import { runCli } from "../cli/run-main.js";
// Simulate: openclaw onboard --flow quickstart
await runCli(["node", "openclaw", "onboard", "--flow", "quickstart"]);
Key Dependencies
| Dependency | Purpose |
|---|---|
| commander | Program tree construction and argv parsing (via buildProgram) |
| dotenv (via loadDotEnv) | Loads .env files into process.env |
| src/infra/env.js | Cross-platform environment normalization |
| src/infra/runtime-guard.js | Enforces minimum Node/Bun version |
| src/cli/route.js | Fast-path binary routing (tryRouteCli) |
| src/plugins/cli.js | Plugin command discovery and registration |