docs: document cli startup helpers

steipete · steipete · commit 20c4e9475a7f · 2026-06-04T11:07:54.000-04:00
diff --git a/src/cli/run-main-policy.ts b/src/cli/run-main-policy.ts
@@ -1,3 +1,4 @@
+// Main CLI startup policy helpers for fast paths, proxy startup, aliases, and missing commands.
 import {
   normalizeLowercaseStringOrEmpty,
   normalizeOptionalLowercaseString,
@@ -82,6 +83,7 @@ function isBareParentDefaultHelpArgv(argv: string[]): boolean {
 }
 
 export function rewriteUpdateFlagArgv(argv: string[]): string[] {
+  // Preserve the old root --update spelling by rewriting before Commander registration.
   const index = argv.indexOf("--update");
   if (index === -1) {
     return argv;
diff --git a/src/cli/run-main.ts b/src/cli/run-main.ts
@@ -1,3 +1,4 @@
+// Main CLI entry orchestration: fast paths, env setup, plugin aliases, and Commander dispatch.
 import { existsSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
@@ -79,6 +80,7 @@ const loadCrestodianModule = async () => await import("../crestodian/crestodian.
 const loadProgressModule = async () => await import("./progress.js");
 
 function createGatewayCliMainStartupTrace(argv: string[]) {
+  // Startup trace is scoped to gateway invocations to avoid routine CLI stderr noise.
   const enabled =
     isTruthyEnvValue(process.env.OPENCLAW_GATEWAY_STARTUP_TRACE) &&
     argv.slice(2).includes("gateway");
diff --git a/src/cli/sandbox-cli.ts b/src/cli/sandbox-cli.ts
@@ -1,3 +1,4 @@
+// Commander registration for sandbox container list, recreate, and explain commands.
 import type { Command } from "commander";
 import { formatDocsLink } from "../../packages/terminal-core/src/links.js";
 import { theme } from "../../packages/terminal-core/src/theme.js";
@@ -44,6 +45,7 @@ const SANDBOX_EXAMPLES = {
 function createRunner(
   commandFn: (opts: CommandOptions, runtime: typeof defaultRuntime) => Promise<void>,
 ) {
+  // Sandbox commands share the default runtime error/exit behavior.
   return async (opts: CommandOptions) => {
     try {
       await commandFn(opts, defaultRuntime);
diff --git a/src/cli/secrets-cli.ts b/src/cli/secrets-cli.ts
@@ -1,3 +1,4 @@
+// Secrets CLI for reload, audit, configure, and apply workflows.
 import type { Command } from "commander";
 import { formatDocsLink } from "../../packages/terminal-core/src/links.js";
 import { theme } from "../../packages/terminal-core/src/theme.js";
@@ -46,6 +47,7 @@ const secretsApplyLoader = createLazyImportLoader<SecretsApplyModule>(
 );
 
 async function readPlanFile(pathname: string): Promise<SecretsApplyPlan> {
+  // Apply consumes a generated plan shape, not arbitrary JSON.
   const [{ readFileSync }, { isSecretsApplyPlan }] = await Promise.all([
     fsModuleLoader.load(),
     import("../secrets/plan.js"),
diff --git a/src/cli/security-cli.ts b/src/cli/security-cli.ts
@@ -1,3 +1,4 @@
+// Security CLI for local/deep audits and safe remediation.
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString,
@@ -43,6 +44,7 @@ function buildAuditGatewayAuthOverride(params: {
   token?: string;
   password?: string;
 }) {
+  // Explicit runtime auth overrides must include the matching credential.
   if (!params.mode) {
     return undefined;
   }
diff --git a/src/cli/setup-onboard-configure-help-fast-path.ts b/src/cli/setup-onboard-configure-help-fast-path.ts
@@ -1,3 +1,4 @@
+// Fast help renderer for setup/onboard/configure without loading full CLI startup.
 import { Command } from "commander";
 import { VERSION } from "../version.js";
 import { resolveCliArgvInvocation } from "./argv-invocation.js";
@@ -66,6 +67,7 @@ async function registerHelpCommand(
 }
 
 export async function tryOutputSetupOnboardConfigureHelp(argv: string[]): Promise<boolean> {
+  // Register only the requested command so help stays quick and avoids config/plugin startup.
   const command = resolveSetupOnboardConfigureHelpCommand(argv);
   if (!command) {
     return false;
diff --git a/src/cli/skills-cli.ts b/src/cli/skills-cli.ts
@@ -1,3 +1,4 @@
+// Skills CLI for workspace status, install/update, ClawHub verification, and workshop proposals.
 import { normalizeOptionalString } from "@openclaw/normalization-core/string-coerce";
 import type { Command } from "commander";
 import { formatDocsLink } from "../../packages/terminal-core/src/links.js";
@@ -72,6 +73,7 @@ function resolveSkillsWorkspace(options?: ResolveSkillsWorkspaceOptions): {
   workspaceDir: string;
   agentId: string;
 } {
+  // Prefer explicit --agent, then infer from cwd, then fall back to configured default agent.
   const config = getRuntimeConfig();
   const explicitAgentId = normalizeOptionalString(options?.agentId);
   const inferredAgentId = explicitAgentId
diff --git a/src/cli/startup-metadata.ts b/src/cli/startup-metadata.ts
@@ -1,3 +1,4 @@
+// Reader/cache for generated CLI startup metadata used by help and completion fast paths.
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -14,6 +15,7 @@ function resolveStartupMetadataPathCandidates(moduleUrl: string): string[] {
 }
 
 export function readCliStartupMetadata(moduleUrl: string): Record<string, unknown> | null {
+  // Check both source and bundled layouts; cache misses too so repeated help stays cheap.
   for (const metadataPath of resolveStartupMetadataPathCandidates(moduleUrl)) {
     const cached = startupMetadataByPath.get(metadataPath);
     if (cached !== undefined) {
diff --git a/src/cli/tagline.ts b/src/cli/tagline.ts
@@ -1,3 +1,4 @@
+// CLI tagline selection helpers, including deterministic random/default/holiday modes.
 import { parseStrictNonNegativeInteger } from "../infra/parse-finite-number.js";
 
 const DEFAULT_TAGLINE = "All your chats, one OpenClaw.";
diff --git a/src/cli/test-runtime-capture.ts b/src/cli/test-runtime-capture.ts
@@ -1,3 +1,4 @@
+// Shared Vitest runtime capture helpers for CLI command output assertions.
 import { vi } from "vitest";
 import type { OutputRuntimeEnv } from "../runtime.js";
 import type { MockFn } from "../test-utils/vitest-mock-fn.js";
@@ -32,6 +33,7 @@ function stringifyRuntimeJson(value: unknown, space = 2): string {
 }
 
 export function createCliRuntimeCapture(): CliRuntimeCapture {
+  // Capture output in arrays while preserving vi mock call inspection.
   const runtimeLogs: string[] = [];
   const runtimeErrors: string[] = [];
   const stringifyArgs = (args: unknown[]) => args.map((value) => String(value)).join(" ");

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,4 @@`
	`1`	`+// CLI tagline selection helpers, including deterministic random/default/holiday modes.`
`1`	`2`	`import { parseStrictNonNegativeInteger } from "../infra/parse-finite-number.js";`
`2`	`3`
`3`	`4`	`const DEFAULT_TAGLINE = "All your chats, one OpenClaw.";`