@remodex/rmx 1.0.2

package/src/cli/provider-runtime.ts

@@ -0,0 +1,179 @@
+import {
+  CliUsageError,
+  csv,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  summaryLines,
+  takeBooleanOption,
+  takeFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  rmx provider edit <name> [--adapter <id>] [--base-url <url>] [--default-model <id|->]
+      [--auth-mode <key|forward|oauth|local|->] [--note <text|->]
+      [--api-key-transport <x-api-key|bearer|->]
+      [--headers <json>] [--enabled <on|off>] [--live-models <on|off>]
+      [--allow-private-network <on|off>] [--json]
+  rmx provider test <name> [--json]
+  rmx provider quota [--refresh] [--json]
+  rmx provider presets [--json]
+  rmx provider account-mode <pool|direct> [--json]
+  rmx provider selected <name> [--set <model,model...>] [--clear] [--json]`;
+
+function cleared(value: string | undefined): string | undefined {
+  return value === "-" ? "" : value;
+}
+
+async function edit(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const name = args.shift()?.trim();
+  if (!name) throw new CliUsageError("provider name is required", USAGE);
+  const wantsJson = takeFlag(args, "--json");
+  const patch: Record<string, unknown> = {};
+  const adapter = takeOption(args, "--adapter");
+  const baseUrl = takeOption(args, "--base-url");
+  const defaultModel = cleared(takeOption(args, "--default-model"));
+  const authMode = cleared(takeOption(args, "--auth-mode"));
+  const note = cleared(takeOption(args, "--note"));
+  const apiKeyTransport = cleared(takeOption(args, "--api-key-transport"));
+  const headers = takeOption(args, "--headers");
+  const enabled = takeBooleanOption(args, "--enabled");
+  const liveModels = takeBooleanOption(args, "--live-models");
+  const allowPrivateNetwork = takeBooleanOption(args, "--allow-private-network");
+  rejectArgs(args, USAGE);
+  if (adapter !== undefined) patch.adapter = adapter;
+  if (baseUrl !== undefined) patch.baseUrl = baseUrl;
+  if (defaultModel !== undefined) patch.defaultModel = defaultModel;
+  if (authMode !== undefined) patch.authMode = authMode;
+  if (note !== undefined) patch.note = note;
+  if (apiKeyTransport !== undefined) patch.apiKeyTransport = apiKeyTransport;
+  if (headers !== undefined) {
+    if (headers === "-") {
+      patch.headers = null;
+    } else {
+      let parsed: unknown;
+      try { parsed = JSON.parse(headers); } catch { throw new CliUsageError("--headers must be valid JSON"); }
+      if (parsed === null) {
+        patch.headers = null;
+      } else if (typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new CliUsageError("--headers must be a JSON object like {\"X-Custom\":\"value\"}");
+      } else {
+        patch.headers = parsed;
+      }
+    }
+  }
+  if (enabled !== undefined) patch.disabled = !enabled;
+  if (liveModels !== undefined) patch.liveModels = liveModels;
+  if (allowPrivateNetwork !== undefined) patch.allowPrivateNetwork = allowPrivateNetwork;
+  if (Object.keys(patch).length === 0) throw new CliUsageError("at least one edit option is required", USAGE);
+  const result = await runtimeRequest(`/api/providers?name=${encodeURIComponent(name)}`, {
+    method: "PATCH",
+    body: JSON.stringify(patch),
+  }, deps);
+  printData(result, wantsJson, [`Updated provider ${name}.`]);
+}
+
+async function testProvider(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const name = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  if (!name) throw new CliUsageError("provider name is required", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<Record<string, unknown>>(`/api/providers/test?name=${encodeURIComponent(name)}`, {
+    method: "POST",
+  }, deps);
+  if (result.applicable === false) {
+    printData(result, wantsJson, [
+      `${name}: not applicable`,
+      "Static catalog; no live model-discovery endpoint to test.",
+    ]);
+    return;
+  }
+  const ok = result.ok === true;
+  printData(result, wantsJson, [
+    `${name}: ${ok ? "connected" : "failed"}`,
+    String(result.message ?? result.error ?? "No detail"),
+    `Latency: ${String(result.latencyMs ?? "?")} ms`,
+  ]);
+  if (!ok) process.exitCode = 1;
+}
+
+async function quota(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  const refresh = takeFlag(args, "--refresh");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest(`/api/provider-quotas${refresh ? "?refresh=1" : ""}`, {}, deps);
+  printData(result, wantsJson, summaryLines(result));
+}
+
+async function presets(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ providers?: unknown[] } | unknown[]>("/api/provider-presets", {}, deps);
+  const rows = Array.isArray(result) ? result : result.providers ?? [];
+  printData(result, wantsJson, rows.map(row => {
+    const record = row as Record<string, unknown>;
+    return `${String(record.id ?? record.name ?? "?")}  ${String(record.label ?? record.adapter ?? "")}`.trimEnd();
+  }));
+}
+
+async function accountMode(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const mode = args.shift();
+  const wantsJson = takeFlag(args, "--json");
+  if (mode !== "pool" && mode !== "direct") throw new CliUsageError("mode must be pool or direct", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest("/api/providers?name=openai", {
+    method: "PATCH",
+    body: JSON.stringify({ codexAccountMode: mode }),
+  }, deps);
+  printData(result, wantsJson, [`OpenAI Codex account mode: ${mode}`]);
+}
+
+async function selected(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const name = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  const set = csv(takeOption(args, "--set"));
+  const clear = takeFlag(args, "--clear");
+  if (!name) throw new CliUsageError("provider name is required", USAGE);
+  if (set !== undefined && clear) throw new CliUsageError("--set and --clear cannot be combined", USAGE);
+  rejectArgs(args, USAGE);
+  if (set === undefined && !clear) {
+    const result = await runtimeRequest<Record<string, unknown>>("/api/selected-models", {}, deps);
+    const selectedMap = (result.selected ?? {}) as Record<string, string[]>;
+    const availableMap = (result.available ?? {}) as Record<string, string[]>;
+    printData({ provider: name, selected: selectedMap[name] ?? [], available: availableMap[name] ?? [] }, wantsJson,
+      [`Selected models for ${name}: ${(selectedMap[name] ?? []).join(", ") || "all"}`]);
+    return;
+  }
+  const models = clear ? [] : (set ?? []);
+  const result = await runtimeRequest("/api/selected-models", {
+    method: "PUT",
+    body: JSON.stringify({ provider: name, models }),
+  }, deps);
+  printData(result, wantsJson, [`${name}: ${models.length ? models.join(", ") : "all models"}`]);
+}
+
+export async function handleProviderRuntimeCommand(sub: string, argv: string[], deps: RuntimeApiDeps = {}): Promise<number | null> {
+  const handlers: Record<string, (args: string[], deps: RuntimeApiDeps) => Promise<void>> = {
+    edit,
+    update: edit,
+    test: testProvider,
+    quota,
+    presets,
+    "account-mode": accountMode,
+    selected,
+  };
+  const handler = handlers[sub];
+  if (!handler) return null;
+  return runCliAction(() => handler(argv, deps));
+}
+
+export const PROVIDER_RUNTIME_USAGE = USAGE;

package/src/cli/provider.ts

@@ -0,0 +1,476 @@
+/**
+ * `rmx provider` subcommand — non-interactive provider management.
+ *
+ * Subcommands:
+ *   list          List configured and available registry providers
+ *   add <name>    Add a provider from the registry or with custom flags
+ *   remove <name> Remove a configured provider
+ *   show <name>   Show provider config details (secrets masked)
+ *   set-default <name>  Change the default provider
+ */
+import { apiKeyTransportConfigError, hasOwnProvider, isValidProviderName, loadConfig, saveConfig } from "../config";
+import { hasHelpFlag } from "./help";
+import { getProviderRegistryEntry, PROVIDER_REGISTRY } from "../providers/registry";
+import { providerConfigSeed } from "../providers/derive";
+import { dropProviderCustomModels } from "../providers/provider-id-rewrite";
+import type { OcxProviderConfig } from "../types";
+import { findLiveProxy } from "../server/proxy-liveness";
+import { syncModelsToCodex } from "../codex/sync";
+import { codexAccountNamespaceProviderCollisionError } from "../codex/account-namespace-match";
+
+// ---------------------------------------------------------------------------
+// Arg helpers
+// ---------------------------------------------------------------------------
+
+function consumeFlag(args: string[], flag: string): boolean {
+  const idx = args.indexOf(flag);
+  if (idx === -1) return false;
+  args.splice(idx, 1);
+  return true;
+}
+
+function consumeFlagValue(args: string[], flag: string): string | undefined {
+  const idx = args.indexOf(flag);
+  if (idx === -1 || idx + 1 >= args.length) return undefined;
+  const value = args[idx + 1];
+  args.splice(idx, 2);
+  return value;
+}
+
+/** Reject any leftover args (unknown flags or trailing values). */
+function rejectUnknownArgs(args: string[], usage: string): void {
+  if (args.length === 0) return;
+  const unknown = args.filter(a => a.startsWith("-"));
+  if (unknown.length > 0) {
+    console.error(`Unknown flag(s): ${unknown.join(", ")}`);
+  } else {
+    console.error(`Unexpected argument(s): ${args.join(", ")}`);
+  }
+  console.error(usage);
+  process.exit(1);
+}
+
+function maskSecret(value: string): string {
+  if (value.length <= 8) return "****";
+  return `${value.slice(0, 4)}****${value.slice(-4)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Validation helper (F1 fix: validate before saveConfig)
+// ---------------------------------------------------------------------------
+
+function validateAndSave(config: ReturnType<typeof loadConfig>): void {
+  if (!config.providers || Object.keys(config.providers).length === 0) {
+    console.error("Error: config would have no providers. Aborting.");
+    process.exit(1);
+  }
+  if (!hasOwnProvider(config.providers, config.defaultProvider)) {
+    console.error(`Error: defaultProvider "${config.defaultProvider}" does not exist in providers. Aborting.`);
+    process.exit(1);
+  }
+  saveConfig(config);
+}
+
+// ---------------------------------------------------------------------------
+// provider list
+// ---------------------------------------------------------------------------
+
+function handleList(args: string[]): void {
+  const wantsJson = consumeFlag(args, "--json");
+  rejectUnknownArgs(args, "Usage: rmx provider list [--json]");
+
+  const config = loadConfig();
+  const configured = Object.keys(config.providers);
+
+  if (wantsJson) {
+    const entries = configured.map(name => {
+      const prov = config.providers[name];
+      const registryEntry = getProviderRegistryEntry(name);
+      return {
+        name,
+        adapter: prov.adapter,
+        baseUrl: prov.baseUrl,
+        authMode: prov.authMode ?? "key",
+        defaultModel: prov.defaultModel ?? null,
+        isDefault: name === config.defaultProvider,
+        source: registryEntry ? "registry" : "custom",
+        models: prov.models ?? [],
+      };
+    });
+    console.log(JSON.stringify({ configured: entries, registryCount: PROVIDER_REGISTRY.length }, null, 2));
+    return;
+  }
+
+  console.log("Configured providers:\n");
+  for (const name of configured) {
+    const prov = config.providers[name];
+    const isDefault = name === config.defaultProvider ? " (default)" : "";
+    const registryEntry = getProviderRegistryEntry(name);
+    const source = registryEntry ? "" : " [custom]";
+    const model = prov.defaultModel ? ` model=${prov.defaultModel}` : "";
+    console.log(`  ${name}${isDefault}${source}  adapter=${prov.adapter}${model}`);
+  }
+
+  const available = PROVIDER_REGISTRY.filter(e => !configured.includes(e.id));
+  if (available.length > 0) {
+    console.log(`\nAvailable from registry (${available.length}):\n`);
+    for (const entry of available) {
+      const auth = entry.authKind === "forward" ? "chatgpt-login" : entry.authKind;
+      console.log(`  ${entry.id.padEnd(24)} ${entry.label}  (${auth})`);
+    }
+    console.log(`\nAdd with: rmx provider add <name> [--api-key <key>]`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// provider add
+// ---------------------------------------------------------------------------
+
+const ADD_USAGE = "Usage: rmx provider add <name> [--adapter <adapter>] [--base-url <url>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <model>] [--allow-private-network] [--set-default] [--force] [--json] [--sync]";
+
+async function handleAdd(args: string[]): Promise<void> {
+  const name = args[0];
+  if (!name || name.startsWith("-")) {
+    console.error(ADD_USAGE);
+    process.exit(1);
+  }
+
+  if (!isValidProviderName(name)) {
+    console.error(`Invalid provider name: "${name}". Use letters, numbers, dots, underscores, or hyphens.`);
+    process.exit(1);
+  }
+
+  const restArgs = args.slice(1);
+  const force = consumeFlag(restArgs, "--force");
+  const setDefault = consumeFlag(restArgs, "--set-default");
+  const wantsJson = consumeFlag(restArgs, "--json");
+  const wantsSync = consumeFlag(restArgs, "--sync");
+  const allowPrivateNetwork = consumeFlag(restArgs, "--allow-private-network");
+  const apiKey = consumeFlagValue(restArgs, "--api-key");
+  const apiKeyTransport = consumeFlagValue(restArgs, "--api-key-transport");
+  const adapter = consumeFlagValue(restArgs, "--adapter");
+  const baseUrl = consumeFlagValue(restArgs, "--base-url");
+  const defaultModel = consumeFlagValue(restArgs, "--default-model");
+  rejectUnknownArgs(restArgs, ADD_USAGE);
+
+  const config = loadConfig();
+
+  const namespaceCollision = codexAccountNamespaceProviderCollisionError(config.codexAccountNamespaces, name);
+  if (namespaceCollision) {
+    console.error(`Error: ${namespaceCollision}.`);
+    process.exit(1);
+  }
+
+  if (hasOwnProvider(config.providers, name) && !force) {
+    console.error(`Provider "${name}" already exists. Use --force to overwrite.`);
+    process.exit(1);
+  }
+
+  let provConfig: OcxProviderConfig;
+  const registryEntry = getProviderRegistryEntry(name);
+
+  if (registryEntry) {
+    provConfig = providerConfigSeed(registryEntry);
+    if (apiKey) {
+      if (registryEntry.authKind === "forward") {
+        console.warn(`Warning: provider "${name}" uses ChatGPT login (forward auth); --api-key is ignored.`);
+      } else if (registryEntry.authKind === "oauth") {
+        console.warn(`Warning: provider "${name}" uses OAuth auth; --api-key is ignored. Run: rmx login ${name}`);
+      } else {
+        provConfig.apiKey = apiKey;
+      }
+    }
+    if (defaultModel) provConfig.defaultModel = defaultModel;
+    if (adapter) provConfig.adapter = adapter;
+    if (baseUrl) provConfig.baseUrl = baseUrl;
+  } else {
+    if (!adapter || !baseUrl) {
+      console.error(`Provider "${name}" is not in the registry. --adapter and --base-url are required.`);
+      console.error("Usage: rmx provider add <name> --adapter <adapter> --base-url <url> [--api-key <key>]");
+      process.exit(1);
+    }
+    provConfig = {
+      adapter,
+      baseUrl,
+      ...(apiKey ? { apiKey } : {}),
+      ...(defaultModel ? { defaultModel } : {}),
+    };
+  }
+
+  if (apiKeyTransport !== undefined) {
+    if (apiKeyTransport !== "x-api-key" && apiKeyTransport !== "bearer") {
+      console.error('Error: --api-key-transport must be "x-api-key" or "bearer".');
+      process.exit(1);
+    }
+    const transportError = apiKeyTransportConfigError({ ...provConfig, apiKeyTransport });
+    if (transportError) {
+      console.error(`Error: ${transportError}.`);
+      process.exit(1);
+    }
+    provConfig.apiKeyTransport = apiKeyTransport;
+  }
+
+  config.providers[name] = provConfig;
+  if (allowPrivateNetwork) provConfig.allowPrivateNetwork = true;
+  if (setDefault) config.defaultProvider = name;
+
+  validateAndSave(config);
+
+  if (wantsJson) {
+    console.log(JSON.stringify({
+      action: "added",
+      provider: name,
+      adapter: provConfig.adapter,
+      baseUrl: provConfig.baseUrl,
+      defaultModel: provConfig.defaultModel ?? null,
+      isDefault: config.defaultProvider === name,
+      source: registryEntry ? "registry" : "custom",
+      needsSync: true,
+    }, null, 2));
+    return;
+  }
+
+  let codexSyncSkipped = false;
+  if (wantsSync) {
+    const live = await findLiveProxy();
+    if (live) {
+      const synced = await syncModelsToCodex(live.port).catch(e => {
+        console.error(`Warning: sync failed: ${e instanceof Error ? e.message : String(e)}`);
+        return null;
+      });
+      if (synced?.status === "skipped") {
+        codexSyncSkipped = true;
+        console.log("Provider saved; Codex integration is OFF, so Codex sync was skipped.");
+      }
+    }
+  }
+
+  const registryLabel = registryEntry ? ` (${registryEntry.label})` : "";
+  console.log(`✅ Provider "${name}"${registryLabel} added.`);
+  if (setDefault) console.log(`   Set as default provider.`);
+  if (registryEntry?.authKind === "oauth") {
+    console.log(`   Authenticate with: rmx login ${name}`);
+  }
+  if (registryEntry?.authKind === "key" && !apiKey) {
+    const envKey = `${name.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}_API_KEY`;
+    console.log(`   Set API key with: rmx provider add ${name} --api-key <key> --force`);
+    console.log(`   Or set env var: ${envKey}`);
+  }
+  if (wantsSync && !codexSyncSkipped) {
+    console.log(`   Models synced to Codex.`);
+  } else {
+    console.log(`   Apply to Codex: rmx sync`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// provider remove
+// ---------------------------------------------------------------------------
+
+function handleRemove(args: string[]): void {
+  const restArgs = [...args];
+  const wantsJson = consumeFlag(restArgs, "--json");
+  const name = restArgs[0];
+  if (!name || name.startsWith("-")) {
+    console.error("Usage: rmx provider remove <name> [--json]");
+    process.exit(1);
+  }
+  rejectUnknownArgs(restArgs.slice(1), "Usage: rmx provider remove <name> [--json]");
+
+  const config = loadConfig();
+  if (!hasOwnProvider(config.providers, name)) {
+    console.error(`Provider "${name}" is not configured.`);
+    process.exit(1);
+  }
+
+  if (name === config.defaultProvider) {
+    console.error(`Cannot remove "${name}" — it is the default provider. Change the default first: rmx provider set-default <other>`);
+    process.exit(1);
+  }
+
+  if (Object.keys(config.providers).length <= 1) {
+    console.error("Cannot remove the last provider.");
+    process.exit(1);
+  }
+
+  const dependentCombos = Object.entries(config.combos ?? {})
+    .filter(([, combo]) => combo.targets.some(target => target.provider === name))
+    .map(([id]) => id)
+    .sort();
+  if (dependentCombos.length > 0) {
+    console.error(`Cannot remove "${name}" — combo(s) depend on it: ${dependentCombos.join(", ")}`);
+    process.exit(1);
+  }
+
+  delete config.providers[name];
+  const droppedCustomModels = dropProviderCustomModels(config, name);
+  validateAndSave(config);
+
+
+  if (wantsJson) {
+    console.log(JSON.stringify({
+      action: "removed",
+      provider: name,
+      remainingProviders: Object.keys(config.providers),
+      defaultProvider: config.defaultProvider,
+      needsSync: true,
+      ...(droppedCustomModels > 0 ? { droppedCustomModels } : {}),
+    }, null, 2));
+    return;
+  }
+
+  console.log(`✅ Provider "${name}" removed.`);
+  if (droppedCustomModels > 0) {
+    const plural = droppedCustomModels === 1 ? "model" : "models";
+    console.log(`   Also removed ${droppedCustomModels} custom ${plural} that belonged to it.`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// provider show
+// ---------------------------------------------------------------------------
+
+function handleShow(args: string[]): void {
+  const restArgs = [...args];
+  const wantsJson = consumeFlag(restArgs, "--json");
+  const name = restArgs[0];
+  if (!name || name.startsWith("-")) {
+    console.error("Usage: rmx provider show <name> [--json]");
+    process.exit(1);
+  }
+  rejectUnknownArgs(restArgs.slice(1), "Usage: rmx provider show <name> [--json]");
+
+  const config = loadConfig();
+  if (!hasOwnProvider(config.providers, name)) {
+    console.error(`Provider "${name}" is not configured.`);
+    process.exit(1);
+  }
+
+  const prov = config.providers[name];
+  const display = {
+    ...prov,
+    ...(prov.apiKey ? { apiKey: maskSecret(prov.apiKey) } : {}),
+    ...(prov.apiKeyPool ? { apiKeyPool: prov.apiKeyPool.map(e => ({ ...e, key: maskSecret(e.key) })) } : {}),
+  };
+
+  if (wantsJson) {
+    console.log(JSON.stringify({ name, isDefault: name === config.defaultProvider, ...display }, null, 2));
+    return;
+  }
+
+  console.log(`Provider: ${name}${name === config.defaultProvider ? " (default)" : ""}`);
+  console.log(`  adapter:      ${display.adapter}`);
+  console.log(`  baseUrl:      ${display.baseUrl}`);
+  if (display.authMode) console.log(`  authMode:     ${display.authMode}`);
+  if (display.apiKey) console.log(`  apiKey:       ${display.apiKey}`);
+  if (display.defaultModel) console.log(`  defaultModel: ${display.defaultModel}`);
+  if (display.models?.length) console.log(`  models:       ${display.models.join(", ")}`);
+}
+
+// ---------------------------------------------------------------------------
+// provider set-default
+// ---------------------------------------------------------------------------
+
+function handleSetDefault(args: string[]): void {
+  const restArgs = [...args];
+  const wantsJson = consumeFlag(restArgs, "--json");
+  const name = restArgs[0];
+  if (!name || name.startsWith("-")) {
+    console.error("Usage: rmx provider set-default <name> [--json]");
+    process.exit(1);
+  }
+  rejectUnknownArgs(restArgs.slice(1), "Usage: rmx provider set-default <name> [--json]");
+
+  const config = loadConfig();
+  if (!hasOwnProvider(config.providers, name)) {
+    console.error(`Provider "${name}" is not configured. Add it first: rmx provider add ${name}`);
+    process.exit(1);
+  }
+
+  if (config.defaultProvider === name) {
+    if (wantsJson) {
+      console.log(JSON.stringify({ action: "noop", provider: name, defaultProvider: name, needsSync: false }, null, 2));
+    } else {
+      console.log(`"${name}" is already the default provider.`);
+    }
+    return;
+  }
+
+  config.defaultProvider = name;
+  validateAndSave(config);
+
+
+  if (wantsJson) {
+    console.log(JSON.stringify({ action: "set-default", provider: name, defaultProvider: name, needsSync: true }, null, 2));
+    return;
+  }
+
+  console.log(`✅ Default provider set to "${name}".`);
+}
+
+// ---------------------------------------------------------------------------
+// Router (F2 fix: handle help flags internally, like service/codex-shim)
+// ---------------------------------------------------------------------------
+
+const PROVIDER_USAGE = `Usage: rmx provider <subcommand>
+
+Subcommands:
+  list                  List configured and available providers
+  add <name>            Add a provider (registry or custom)
+  edit <name>           Edit live provider fields
+  test <name>           Test the provider's upstream model endpoint
+  remove <name>         Remove a configured provider
+  show <name>           Show provider config details
+  set-default <name>    Change the default provider
+  selected <name>       Show or set the provider model allowlist
+  quota                 Show provider quota reports
+  presets               List GUI provider presets
+  account-mode <mode>   Set OpenAI Codex pool/direct mode
+
+Examples:
+  rmx provider list
+  rmx provider add anthropic --api-key sk-ant-...
+  rmx provider add my-ollama --adapter openai-chat --base-url http://localhost:11434/v1
+  rmx provider show anthropic --json
+  rmx provider set-default anthropic
+  rmx provider remove my-ollama`;
+
+export async function handleProviderCommand(args: string[]): Promise<void> {
+  const sub = args[0];
+
+  if (!sub || sub === "help" || hasHelpFlag(args)) {
+    console.log(PROVIDER_USAGE);
+    process.exit(0);
+  }
+
+  const subArgs = args.slice(1);
+
+  switch (sub) {
+    case "list":
+      handleList(subArgs);
+      break;
+    case "add":
+      await handleAdd(subArgs);
+      break;
+    case "remove":
+      handleRemove(subArgs);
+      break;
+    case "show":
+      handleShow(subArgs);
+      break;
+    case "set-default":
+      handleSetDefault(subArgs);
+      break;
+    default: {
+      const { handleProviderRuntimeCommand } = await import("./provider-runtime");
+      const code = await handleProviderRuntimeCommand(sub, subArgs);
+      if (code !== null) {
+        process.exitCode = code;
+        break;
+      }
+      console.error(`Unknown provider subcommand: ${sub}`);
+      console.error(PROVIDER_USAGE);
+      process.exit(1);
+    }
+  }
+}