src/cli/program/core-command-descriptors.ts

// Core root-command descriptor catalog used for help placeholders and lazy registration.
import { isExperimentalClawsEnabled } from "../../claws/experimental.js";
import { isConfigMachineOutput } from "../config-output-mode.js";
import { isDoctorMachineOutput } from "../doctor-output-mode.js";
import { hasMachineOutputOption } from "../machine-output-argv.js";
import type { NamedCommandDescriptor } from "./command-group-descriptors.js";

/** Descriptor shape for root commands owned by the core CLI. */
type CoreCliCommandDescriptor = NamedCommandDescriptor;

/** Static root-command descriptors for the core CLI surface. */
export const CORE_CLI_COMMAND_DESCRIPTORS = [
  {
    name: "setup",
    description: "Chat with OpenClaw; onboard when setup is incomplete",
    hasSubcommands: false,
  },
  {
    name: "crestodian", // hidden alias
    description: "Deprecated: use openclaw setup",
    hasSubcommands: false,
    hidden: true,
  },
  {
    name: "onboard",
    description: "Guided setup for auth, models, Gateway, workspace, channels, and skills",
    hasSubcommands: true,
  },
  {
    name: "configure",
    description: "Interactive configuration for credentials, channels, gateway, and agent defaults",
    hasSubcommands: false,
  },
  {
    name: "config",
    description:
      "Non-interactive config helpers (get/set/patch/unset/file/schema/validate). Run without subcommand for guided setup.",
    hasSubcommands: true,
    machineOutput: ({ argv }) => isConfigMachineOutput(argv),
  },
  {
    name: "claws",
    description: "Inspect and add experimental OpenClaw Claws",
    hasSubcommands: true,
    parentDefaultHelp: true,
  },
  {
    name: "backup",
    description: "Create, verify, and restore backup archives and SQLite snapshots",
    hasSubcommands: true,
  },
  {
    name: "database",
    description: "Inspect database schema compatibility and shared-state write ownership",
    hasSubcommands: true,
    parentDefaultHelp: true,
  },
  {
    name: "migrate",
    description: "Import state from another agent system",
    hasSubcommands: true,
  },
  {
    name: "doctor",
    description: "Health checks + quick fixes for the gateway and channels",
    hasSubcommands: false,
    machineOutput: isDoctorMachineOutput,
  },
  {
    name: "triage",
    description: "Collect sanitized diagnostics and open a local coding agent for repair",
    hasSubcommands: false,
    machineOutput: ({ argv }) => hasMachineOutputOption(argv, "--json"),
  },
  {
    name: "dashboard",
    description: "Open the Control UI with your current token",
    hasSubcommands: false,
  },
  {
    name: "reset",
    description: "Reset local config/state (keeps the CLI installed)",
    hasSubcommands: false,
  },
  {
    name: "uninstall",
    description: "Uninstall the gateway service + local data",
    hasSubcommands: false,
  },
  {
    name: "message",
    description: "Send, read, and manage messages and channel actions",
    hasSubcommands: true,
  },
  {
    name: "mcp",
    description: "Manage OpenClaw mcp.servers config and channel bridge",
    hasSubcommands: true,
    parentDefaultHelp: true,
  },
  {
    name: "transcripts",
    description: "Inspect stored transcripts",
    hasSubcommands: true,
  },
  {
    name: "agent",
    description: "Run an agent turn via the Gateway (use --local for embedded)",
    hasSubcommands: true,
  },
  {
    name: "agents",
    description: "Manage isolated agents (workspaces + auth + routing)",
    hasSubcommands: true,
  },
  {
    name: "status",
    description: "Show channel health and recent session recipients",
    hasSubcommands: false,
  },
  {
    name: "health",
    description: "Fetch health from the running gateway",
    hasSubcommands: false,
  },
  {
    name: "audit",
    description: "Inspect activity records and exact-run identity context",
    hasSubcommands: false,
  },
  {
    name: "sessions",
    description: "List stored conversation sessions",
    hasSubcommands: true,
  },
  {
    name: "tasks",
    description: "Inspect durable background tasks and TaskFlow state",
    hasSubcommands: true,
  },
] as const satisfies ReadonlyArray<CoreCliCommandDescriptor>;

/** Return core root-command descriptors in help/registration order. */
export function getCoreCliCommandDescriptors(): ReadonlyArray<CoreCliCommandDescriptor> {
  return isExperimentalClawsEnabled()
    ? CORE_CLI_COMMAND_DESCRIPTORS
    : CORE_CLI_COMMAND_DESCRIPTORS.filter((descriptor) => descriptor.name !== "claws");
}

/** Return names for all core root commands. */
export function getCoreCliCommandNamesCore(): string[] {
  return getCoreCliCommandDescriptors().map((descriptor) => descriptor.name);
}

/** Return core root commands that own child subcommands. */
export function getCoreCliCommandsWithSubcommands(): string[] {
  return getCoreCliCommandDescriptors()
    .filter((descriptor) => descriptor.hasSubcommands)
    .map((descriptor) => descriptor.name);
}

/** Return core root commands whose parent action should default to help. */
export function getCoreCliParentDefaultHelpCommands(): string[] {
  return getCoreCliCommandDescriptors()
    .filter((descriptor) => descriptor.parentDefaultHelp)
    .map((descriptor) => descriptor.name);
}