@remodex/rmx 1.0.2

package/src/cli/export-command.ts

@@ -0,0 +1,201 @@
+/**
+ * `rmx export --client <id>` — print a client config for the live proxy.
+ *
+ * Seven clients, four formats: opencode and Pi are JSON, OMP, Hermes and Gajae
+ * are YAML, OpenClaw JSON5, Kimi TOML.
+ *
+ * Two consumers, one payload (devlog 260731_client_config_export/020):
+ *
+ * - **Agent** (`--json`): stdout is exactly the client config as JSON and nothing else,
+ *   so `rmx export --client pi --json > models.json` is safe to pipe. This is JSON for
+ *   every client, including the YAML/JSON5/TOML ones — the flag is about machine
+ *   readability, not the client's native format. Every diagnostic — including the
+ *   `--out` write note — goes to stderr.
+ * - **Human** (no flag) and `--out`: the client's NATIVE serialization leads, then the
+ *   destination path, the merge warning, the env export line, and the model/degraded
+ *   counts.
+ *
+ * The command never writes the user's real config path. `--out` is an explicit target and
+ * refuses to clobber an existing file without `--force`, because the common mistake
+ * (`--out ~/.config/opencode/opencode.json`) would silently destroy other providers.
+ *
+ * Serialization itself belongs to src/clients/config-export.ts; this module only resolves
+ * the base URL, filters the catalog, and renders. No secret is ever serialized: the config
+ * carries the client's documented env reference — or, for Kimi, which cannot hold one, a
+ * loopback placeholder — and the real key stays in the environment.
+ */
+import { writeFileSync } from "node:fs";
+import { loadConfig } from "../config";
+import {
+  EXPORT_CLIENTS,
+  EXPORT_CLIENT_IDS,
+  buildClientConfigText,
+  isExportClientId,
+  opencodeProxyBaseUrl,
+  type ExportClientId,
+  type ExportModel,
+} from "../clients/config-export";
+import { opencodeCatalogFromProxyRows, type OpencodeProxyModelRow } from "./opencode";
+import type { OcxConfig } from "../types";
+import {
+  CliUsageError,
+  RuntimeApiError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeBaseUrl,
+  runtimeRequest,
+  takeFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  rmx export --client <${EXPORT_CLIENT_IDS.join("|")}> [--json] [--out <path>] [--force]`;
+
+export interface ExportCommandDeps extends RuntimeApiDeps {
+  /** Live config seam; tests inject a fixture instead of reading the user's config. */
+  configImpl?: () => OcxConfig;
+}
+
+/**
+ * `/api/models` row plus the modality list Pi consumes. The launcher's row type predates
+ * the Pi exporter and stops at the fields OpenCode needs.
+ */
+type ExportProxyModelRow = OpencodeProxyModelRow & { inputModalities?: string[] };
+
+/** Same authoritativeness rule the serializers apply, for the degraded-count line. */
+function hasContextLimit(model: ExportModel): boolean {
+  return typeof model.contextWindow === "number"
+    && Number.isFinite(model.contextWindow)
+    && model.contextWindow > 0;
+}
+
+/**
+ * Export rows from proxy `/api/models` rows.
+ *
+ * `opencodeCatalogFromProxyRows` owns the visibility rules (drop `disabled`, drop dupes,
+ * drop native under Codex Direct) — the export core does none of that, so a row filtered
+ * here is the only thing keeping a disabled model out of a client's picker. Modalities are
+ * re-joined by `namespaced` because the launcher's catalog type does not carry them.
+ */
+export function exportModelsFromProxyRows(
+  rows: readonly ExportProxyModelRow[],
+  config: OcxConfig,
+): ExportModel[] {
+  const modalities = new Map<string, string[]>();
+  for (const row of rows) {
+    const namespaced = row.namespaced?.trim();
+    if (namespaced && Array.isArray(row.inputModalities) && row.inputModalities.length > 0) {
+      if (!modalities.has(namespaced)) modalities.set(namespaced, [...row.inputModalities]);
+    }
+  }
+  return opencodeCatalogFromProxyRows(rows, config).map(entry => {
+    const model: ExportModel = {
+      namespaced: entry.namespaced,
+      provider: entry.provider ?? (entry.native ? "openai" : "routed"),
+      id: entry.id ?? entry.namespaced,
+    };
+    if (entry.native) model.native = true;
+    if (entry.displayName) model.displayName = entry.displayName;
+    if (entry.contextWindow !== undefined) model.contextWindow = entry.contextWindow;
+    const input = modalities.get(entry.namespaced);
+    if (input) model.inputModalities = input;
+    return model;
+  });
+}
+
+/**
+ * `http://host:port/v1` for the proxy that is actually listening.
+ *
+ * `runtimeBaseUrl` is the identity-checked `findLiveProxy` probe the launcher uses, and it
+ * already throws the "Start it with: rmx start" error when nothing answers — so a config
+ * with an empty models block can never be emitted.
+ *
+ * Resolved ONCE and handed back to `runtimeRequest` as `baseUrl`, so the catalog and the
+ * exported endpoint can never come from two different probes.
+ */
+function proxyV1BaseUrl(root: string): string {
+  const url = new URL(root);
+  const port = url.port ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
+  return opencodeProxyBaseUrl(port, url.hostname);
+}
+
+function parseClient(args: string[]): ExportClientId {
+  const raw = takeOption(args, "--client");
+  if (raw === undefined) {
+    throw new CliUsageError(`--client is required (${EXPORT_CLIENT_IDS.join(", ")})`, USAGE);
+  }
+  const client = raw.trim().toLowerCase();
+  if (!isExportClientId(client)) {
+    throw new CliUsageError(`--client must be one of: ${EXPORT_CLIENT_IDS.join(", ")}`, USAGE);
+  }
+  return client;
+}
+
+/**
+ * Write the config, refusing to replace an existing file without `--force`.
+ *
+ * The `wx` flag does the refusal in the kernel rather than after an `existsSync` check, so
+ * a file created between the two can never be truncated. Nothing is printed before this
+ * runs: a refusal leaves both the target bytes and stdout untouched.
+ */
+function writeExport(path: string, text: string, force: boolean): void {
+  try {
+    writeFileSync(path, text, force ? { encoding: "utf8" } : { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      throw new CliUsageError(
+        `${path} already exists. Re-run with --force to replace it, or print the config and merge it yourself.`,
+        USAGE,
+      );
+    }
+    throw error;
+  }
+}
+
+export async function handleExportCommand(argv: string[], deps: ExportCommandDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const client = parseClient(args);
+    const wantsJson = takeFlag(args, "--json");
+    const force = takeFlag(args, "--force");
+    const out = takeOption(args, "--out");
+    rejectArgs(args, USAGE);
+
+    const spec = EXPORT_CLIENTS[client];
+    const config = (deps.configImpl ?? loadConfig)();
+    const root = await runtimeBaseUrl(deps);
+    const rows = await runtimeRequest<ExportProxyModelRow[]>("/api/models", {}, { ...deps, baseUrl: root });
+    if (!Array.isArray(rows)) {
+      throw new RuntimeApiError("Management API returned an unexpected /api/models payload.", 502, rows);
+    }
+    const models = exportModelsFromProxyRows(rows, config);
+    // The text is the client's OWN format — YAML, TOML and JSON5 clients would
+    // otherwise receive a JSON rendering their parser reads differently.
+    const built = buildClientConfigText(client, { baseUrl: proxyV1BaseUrl(root), models, config });
+    const clientConfig = built.document;
+    const text = built.text;
+
+    // Every serializer already ends with exactly one newline.
+    if (out !== undefined) writeExport(out, text, force);
+    // stderr, so `--json` stdout stays a standalone JSON document.
+    if (out !== undefined && wantsJson) console.error(`Wrote ${out}`);
+
+    const degraded = models.filter(model => !hasContextLimit(model)).length;
+    // `--json` keeps emitting the DOCUMENT at the top level as JSON for scripts;
+    // `--out` is the path that writes the selected client's native format.
+    // Format metadata rides in the human lines below.
+    printData(clientConfig, wantsJson, [
+      text.trimEnd(),
+      "",
+      ...(out !== undefined ? [`Wrote ${out}`] : []),
+      `Destination: ${spec.destination(process.env)}`,
+      "Merge this provider block into that file; do not replace it.",
+      `Before launching: ${spec.exportHint}`,
+      `${models.length} model${models.length === 1 ? "" : "s"}; ${degraded} omit context limits (the client applies its own defaults).`,
+    ]);
+  });
+}
+
+export const EXPORT_USAGE = USAGE;

package/src/cli/help.ts

@@ -0,0 +1,370 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const repoRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta.url)));
+
+type HelpEntry = {
+  usage: string;
+  summary: string;
+  details?: string[];
+};
+
+const CANONICAL_CLI = "rmx";
+const COMPATIBILITY_ALIASES = ["remodex", "opencodex", "ocx"] as const;
+
+function canonicalCommand(value: string): string {
+  // Help text contains paths such as `ocx.pid`; replace only command-shaped
+  // tokens so compatibility filenames and environment names remain accurate.
+  return value.replace(/\bocx(?=\s|$|[`|])/g, CANONICAL_CLI);
+}
+
+const helpEntries: Record<string, HelpEntry> = {
+  init: { usage: "rmx init", summary: "Interactive setup for providers and Codex config injection." },
+  setup: { usage: "rmx setup", summary: "Interactive setup for providers and Codex config injection (alias of init)." },
+  start: { usage: "rmx start [--port <port>]", summary: "Start the proxy server and sync models to Codex." },
+  stop: { usage: "rmx stop", summary: "Stop the proxy and restore native Codex config." },
+  restore: {
+    usage: "rmx restore [back]",
+    summary: "Restore native Codex config without stopping the proxy; `restore back` re-points codex at the running proxy.",
+  },
+  eject: {
+    usage: "rmx eject [back]",
+    summary: "Restore native Codex config without stopping the proxy; `eject back` re-points codex at the running proxy.",
+  },
+  "recover-history": {
+    usage: "rmx recover-history --legacy-openai",
+    summary: "Explicitly recover pre-backup syncResumeHistory rows.",
+  },
+  uninstall: {
+    usage: "rmx uninstall",
+    summary: "Remove service/shim/config and restore native Codex.",
+    details: [
+      "Alias: rmx remove",
+      "Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
+    ],
+  },
+  remove: {
+    usage: "rmx remove",
+    summary: "Remove service/shim/config and restore native Codex.",
+    details: [
+      "Alias of: rmx uninstall",
+      "Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
+    ],
+  },
+  service: {
+    usage: "rmx service [install|repair|start|stop|status|uninstall|remove] [--native|--scheduler]",
+    summary: "Run as a background service.",
+    details: [
+      "With no subcommand, installs/updates and starts the background service.",
+      "Use `rmx service status` to see diagnostics and log paths.",
+    ],
+  },
+  "codex-shim": {
+    usage: "rmx codex-shim <install|status|uninstall|remove>",
+    summary: "Auto-start the proxy when `codex` launches.",
+    details: ["Use `remove` as an alias for `uninstall`."],
+  },
+  tray: {
+    usage: "rmx tray <install|start|stop|status|uninstall|remove> [--json] [--no-start]",
+    summary: "Install and control the Windows status tray icon.",
+    details: [
+      "The tray starts at Windows login and provides one-click proxy controls.",
+      "Tray start/stop controls the icon only; use its menu to start or stop the proxy.",
+      "--no-start (install only) installs the tray without launching it immediately.",
+    ],
+  },
+  ensure: { usage: "rmx ensure", summary: "Ensure the proxy is running and Codex config/cache are current." },
+  sync: {
+    usage: "rmx sync [--restart-codex]",
+    summary: "Fetch provider models and inject them into Codex config.",
+    details: [
+      "After writing the catalog, warns if long-lived Codex app-server processes are still running.",
+      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+    ],
+  },
+  "sync-cache": {
+    usage: "rmx sync-cache [--restart-codex]",
+    summary: "Refresh Codex's model cache from the active catalog.",
+    details: [
+      "Warns when Codex app-server processes still hold an in-memory model list.",
+      "--restart-codex sends SIGTERM only to matching app-server / code-mode-host processes (may interrupt active turns).",
+    ],
+  },
+  status: { usage: "rmx status", summary: "Check proxy server status." },
+  doctor: { usage: "rmx doctor", summary: "Diagnose environment/network issues (paths, WSL /mnt, proxy env, ChatGPT reachability)." },
+  debug: {
+    usage: "rmx debug <provider|usage|injection|claude> <on|off|status|reset|logs [-f]>",
+    summary: "Show or toggle runtime provider, usage, injection, and Claude debug capture.",
+    details: [
+      "Provider: rmx debug provider on | off | status | reset | logs [-f]",
+      "Usage JSONL: rmx debug usage on | off | status | reset | logs [-f]",
+      "Env default: OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)",
+    ],
+  },
+  login: { usage: "rmx login <provider>", summary: "OAuth or API-key login for a provider." },
+  logout: { usage: "rmx logout <provider>", summary: "Remove a stored provider login." },
+  gui: { usage: "rmx gui", summary: "Open the Remodex dashboard." },
+  update: {
+    usage: "rmx update [--tag latest|preview]",
+    summary: "Update Remodex. Preview installs stay on the preview tag unless overridden.",
+  },
+  provider: {
+    usage: "rmx provider <list|add|edit|test|remove|show|set-default|selected|quota|presets|account-mode>",
+    summary: "Non-interactive provider management.",
+    details: [
+      "Subcommands: list, add/edit/test/remove/show, set-default, selected, quota, presets, account-mode",
+      "Registry providers are auto-configured by name. Custom providers need --adapter and --base-url.",
+      "Run `rmx provider --help` for full usage and examples.",
+    ],
+  },
+  account: {
+    usage: "rmx account <list|current|use|refresh|auto-switch|priority|login|reauth|code|cancel|remove|add-key|reset-credits|main> ...",
+    summary: "List and switch provider accounts and API-key pools (GUI parity).",
+    details: [
+      "list [provider]     Codex account pool, OAuth accounts and API keys (identifiers shown masked as the API returns them).",
+      "current <provider>  Show the active account or key.",
+      "use <provider> <id> Switch the active credential; 'main' selects the Codex App login.",
+      "refresh <provider>  Force-refresh Codex or provider quota reports.",
+      "auto-switch <provider> <on|off|status|threshold N>  Control the Codex pool threshold.",
+      "priority <provider> <id|main> [first|earlier|normal|later|last|-100..100|reset]  Selection order; omit the value to read it.",
+      "remove <provider> <id> --yes  Remove a stored account or key after an existence check.",
+      "add-key <provider> [--label <label>]  Add a key read only from piped stdin.",
+      "login/reauth/code/cancel  Run browser or manual-code auth from a headless shell.",
+      "reset-credits <id|main> [--consume --yes]  Inspect or consume Codex reset credits.",
+      "main <subcommand>     Manage the physical native Codex login separately from Pool routing.",
+      "Switching the active account takes effect immediately; running threads move on their next request, and in-flight requests keep the account they captured.",
+      "A selection-order change applies from the next unbound request and never moves a bound thread.",
+    ],
+  },
+  models: {
+    usage: "rmx models <list|live|add|edit|remove|enable|disable|provider|selected|context|shadow> ...",
+    summary: "List models and manage custom (manually registered) models.",
+    details: [
+      "List available models from static config with no subcommand (liveModels may add more at runtime).",
+      "add: register a model the provider catalog does not advertise yet.",
+      "  --display-name <name>     Human label (no slashes).",
+      "  --context-window <tokens> e.g. 200000.",
+      "  --modalities text,image   Comma-separated (text|image|audio).",
+      "remove: delete a custom model by UUID or <provider>/<modelId>.",
+      "list-custom: show all custom models.",
+      "Changes apply immediately to a running proxy (catalog sync).",
+    ],
+  },
+  model: {
+    usage: "rmx model <subcommand>",
+    summary: "Alias of rmx models.",
+  },
+  combo: {
+    usage: "rmx combo <list|show|set|remove> ...",
+    summary: "Manage combo failover and round-robin virtual models.",
+    details: ["Alias hierarchy: rmx route combo ...", "Use --targets provider/model[:weight],provider/model[:weight]."],
+  },
+  route: {
+    usage: "rmx route combo <list|show|set|remove> ...",
+    summary: "Manage routing features; combo is currently the supported routing resource.",
+  },
+  agent: {
+    usage: "rmx agent <status|injection|effort|subagents|fallback|sidecar> ...",
+    summary: "Manage headless multi-agent, roster, effort, injection, and sidecar settings.",
+  },
+  observe: {
+    usage: "rmx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...",
+    summary: "Inspect proxy requests, usage, storage, memory, and debug data.",
+  },
+  logs: { usage: "rmx logs [filters] [--follow] [--json|--jsonl]", summary: "Alias of rmx observe logs." },
+  usage: { usage: "rmx usage [--range <7d|30d|all>] [--surface <all|codex|claude|grok>] [--json]", summary: "Alias of rmx observe usage." },
+  storage: { usage: "rmx storage [--json]", summary: "Alias of rmx observe storage." },
+  memory: { usage: "rmx memory [--json]", summary: "Alias of rmx observe memory." },
+  access: {
+    usage: "rmx access <key|endpoints|models|test> ...",
+    summary: "Manage Remodex admission API keys and inspect external endpoints.",
+  },
+  "api-key": { usage: "rmx api-key <list|create|remove> ...", summary: "Alias of rmx access key." },
+  export: {
+    usage: "rmx export --client <opencode|pi|omp|hermes|openclaw|kimi|gajae> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (opencode, Pi, OMP, Hermes, OpenClaw, Kimi Code, Gajae Code) wired to the running proxy.",
+    details: [
+      "--json prints the generated document as JSON on stdout; use --out for the client's native format.",
+      "--out <path> writes the native config there and refuses to replace an existing file without --force.",
+      "The config never contains a real key; it carries a documented env reference or a non-secret loopback placeholder.",
+      "The destination path is printed for merging by hand — rmx never writes your real client config.",
+    ],
+  },
+  grok: { usage: "rmx grok <status|exclude|include|set|clear|apply> ...", summary: "Manage and apply the Grok Build model fence." },
+  integration: { usage: "rmx integration <claude|grok|client> ...", summary: "Manage supported client integrations." },
+  system: {
+    usage: "rmx system <status|settings|startup|diagnostics|sync|update|desktop-update> ...",
+    summary: "Manage headless runtime settings, startup, sync, diagnostics, and updates.",
+    details: [
+      "desktop-update check [--channel latest|preview]  Check the native desktop release manifest.",
+      "desktop-update run [--channel latest|preview]    Download and verify a native desktop update.",
+      "desktop-update status                            Show shared tray/dashboard update state.",
+      "Headless commands never install a native package; installation requires the desktop shell.",
+    ],
+  },
+  config: {
+    usage: "rmx config <show|get|set|unset|validate|export|import> ...",
+    summary: "Inspect and safely modify validated Remodex configuration.",
+    details: ["Secrets are masked by show/get. Import requires --yes and validates before writing."],
+  },
+  claude: {
+    usage: "rmx claude [claude args...]",
+    summary: "Launch Claude Code wired to the proxy (env injection + gateway model discovery).",
+    details: [
+      "Ensures the proxy is running, then execs `claude` with ANTHROPIC_BASE_URL/ANTHROPIC_AUTH_TOKEN,",
+      "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1 and model slots from config.claudeCode.",
+      "Routed models appear in the native /model picker with stable claude-opus-4-8-2026MMDD slot aliases (Claude Code >= 2.1.129).",
+      "Older versions: pick models via ANTHROPIC_MODEL or /model <id> directly (any string passes through).",
+      "User-exported ANTHROPIC_* variables always take precedence.",
+      "",
+      "Claude Desktop profile:",
+      "  rmx claude desktop [apply]                         Save and apply the four-family profile",
+      "  rmx claude desktop show [--json]                   Show routes, families, and defaults",
+      "  rmx claude desktop move <route> <family> [--default]",
+      "  rmx claude desktop default <family> <route|none>",
+      "  rmx claude desktop export <path|->                 Export versioned JSON (`-` = stdout)",
+      "  rmx claude desktop import <path> [--apply]         Validate and import JSON",
+      "Families: opus, fable, sonnet, haiku. New routes start in opus.",
+      "`none` is valid only when that family is empty.",
+      "Legacy apply flags remain supported: --static, --hybrid, --discovery-only.",
+      "",
+      "Claude Code settings: rmx claude config <status|set> ...",
+    ],
+  },
+  opencode: {
+    usage: "rmx opencode [opencode args...]",
+    summary: "Launch opencode wired to the proxy (runtime provider config).",
+    details: [
+      "Ensures the proxy is running, then execs `opencode` with the generated `provider.opencodex`",
+      "block injected through OpenCode's inline runtime layer (`OPENCODE_CONFIG_CONTENT`). Any",
+      "existing inline config in the environment is preserved and only `provider.opencodex` is",
+      "overwritten for this launch.",
+      "Global/project opencode.json may be read to warn about an existing provider.opencodex",
+      "override; on-disk files are never modified.",
+      "Routed models appear in the model picker under Remodex using the compatibility id opencodex/<provider>/<model>.",
+      "Stop using `rmx opencode` and plain `opencode` behaves exactly as before.",
+    ],
+  },
+  restart: {
+    usage: "rmx restart",
+    summary: "Stop the proxy and restart it (background). Equivalent to stop + ensure.",
+  },
+  v2: {
+    usage: "rmx v2 <status|on|off|mode <v1|default|v2>|threads <n>>",
+    summary: "Toggle the Codex multi_agent_v2 feature (multi-agent surface).",
+    details: [
+      "status                Show flag, multi-agent mode, and thread limit.",
+      "on | off              Enable/disable multi_agent_v2 (catalog resyncs).",
+      "mode <v1|default|v2>  Force all models to one surface, or respect upstream pins.",
+      "threads <n>           Set max_concurrent_threads_per_session (integer >= 1).",
+      "Flips preserve the active thread limit while moving between v1/v2 modes.",
+    ],
+  },
+  health: {
+    usage: "rmx health [--json]",
+    summary: "Check proxy health. Exits 0 if healthy, 1 otherwise.",
+    details: ["Use --json for structured output: {ok, pid, port}."],
+  },
+  ready: {
+    usage: "rmx ready [--json] [--wait [--timeout <seconds>]]",
+    summary: "Check post-sync readiness. Exits 0 only when ready.",
+    details: [
+      "Exact unauthenticated GET /readyz returns HTTP 200 when ready, or 503 with Retry-After: 1 for pending or failed.",
+      "Its sanitized HTTP identity is {service, version, uptime, pid, port, status}; /healthz is separate liveness, not readiness.",
+      "Default is a single identity-checked /readyz probe; old proxies without /readyz fail closed as unreachable.",
+      "--wait polls until ready or timeout, but exits immediately on terminal failed (default 45s, max 300s).",
+      "--timeout requires --wait and accepts a positive integer (1..300).",
+      "--json emits {ready, status, pid, port}; status is one of ready|pending|failed|unreachable.",
+      "Invalid or unknown arguments exit 64. Not-ready, pending, failed, timeout, and unreachable exit 1.",
+    ],
+  },
+};
+
+function packageVersion(): string {
+  const raw = readFileSync(join(repoRoot, "package.json"), "utf8");
+  const parsed = JSON.parse(raw) as { version?: unknown };
+  return typeof parsed.version === "string" ? parsed.version : "unknown";
+}
+
+export function printVersion(): void {
+  console.log(`Remodex ${packageVersion()}`);
+}
+
+export function printUsage(): void {
+  const canonical = `Remodex (rmx) — Universal provider proxy for Codex
+
+Usage:
+  rmx setup                   Interactive setup (alias: init)
+  rmx start [--port <port>]   Start the proxy server (auto-syncs models to Codex)
+  rmx stop                    Stop the proxy AND restore native Codex (plain codex works again)
+  rmx restore                 Restore native Codex without stopping (alias: eject)
+  rmx restore back            Re-point codex at the running proxy (undo restore)
+  rmx recover-history --legacy-openai
+                               Explicitly recover pre-backup syncResumeHistory rows
+  rmx uninstall               Remove service/shim/config and restore native Codex (alias: remove)
+  rmx service [sub]           Run as a background service (default: install/update/start)
+  rmx codex-shim <sub>        Auto-start proxy when \`codex\` launches (install|status|uninstall|remove)
+  rmx tray <sub>              Windows status tray (install|start|stop|status|uninstall)
+  rmx ensure                  Ensure the proxy is running and Codex config/cache are current
+  rmx sync [--restart-codex]  Fetch models from providers and inject into Codex config
+  rmx sync-cache [--restart-codex]
+                              Refresh Codex's model cache from the active catalog
+  rmx status                  Check proxy server status
+  rmx doctor                  Diagnose environment/network issues (WSL, proxy, ChatGPT reachability)
+  rmx debug <scope>           provider/usage/injection/claude on|off|status|reset
+  rmx login <provider>        OAuth or API-key provider login
+  rmx logout <provider>       Remove a stored OAuth login
+  rmx gui                     Open the Remodex dashboard
+  rmx update [--tag <tag>]    Update Remodex (keeps preview installs on @preview)
+  rmx restart                  Stop and restart the proxy
+  rmx v2 <sub>                multi_agent_v2 surface (status|on|off|mode|threads)
+  rmx health [--json]          Check proxy health (exit 0=healthy, 1=not)
+  rmx ready [--json] [--wait [--timeout <s>]]  Check post-sync readiness (exit 0 only when ready)
+  rmx provider <sub>          Providers, connectivity, quota, and selected models
+  rmx account <sub>           Accounts, login/reauth, key pools, and quota controls
+  rmx models <sub>            Live/custom models, visibility, context, and shadow calls
+  rmx combo <sub>             Combo failover/round-robin routing
+  rmx agent <sub>             Subagents, injection, effort caps, and sidecars
+  rmx observe <sub>           Logs, usage, storage, memory, and debug data
+  rmx access <sub>            External API keys and endpoint information
+  rmx export --client <id>    Print a client config wired to the running proxy (7 clients)
+  rmx integration client <sub> Enable, disable, inspect or roll back a client integration
+  rmx grok <sub>              Grok Build model selection and apply
+  rmx system <sub>            Runtime settings, startup, sync, diagnostics, and updates
+  rmx config <sub>            Validated configuration show/get/set/import/export
+  rmx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
+  rmx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile
+  rmx opencode [args...]      Launch opencode wired to the proxy (runtime provider config)
+  rmx help [command]          Show help
+  rmx --version | -v          Print version
+
+Examples:
+  rmx init                    Set up provider and inject into Codex
+  rmx start                   Start on default port (10100)
+  rmx start --port 8080       Start on custom port
+  rmx help service            Show service command help
+  rmx sync                    Sync available models to Codex`;
+  console.log(`${canonical}
+
+Compatibility aliases: ${COMPATIBILITY_ALIASES.join(", ")}
+These aliases accept the same commands as rmx.`);
+}
+
+export function hasHelpFlag(values: string[]): boolean {
+  return values.some(value => value === "--help" || value === "-h" || value === "help");
+}
+
+export function printSubcommandUsage(name: string | undefined): void {
+  const entry = name ? helpEntries[name] : undefined;
+  if (!entry) {
+    console.error(`Unknown command: ${name ?? ""}`.trim());
+    printUsage();
+    process.exit(1);
+  }
+  const canonicalUsage = canonicalCommand(entry.usage);
+  console.log(`Usage: ${canonicalUsage}\n\n${canonicalCommand(entry.summary)}`);
+  if (entry.details?.length) {
+    console.log(`\n${entry.details.map(canonicalCommand).join("\n")}`);
+  }
+}