Skip to content

refactor(cli): add command registry as single metadata source #1446

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Wibias merged 2 commits into from
Aug 11, 2026
+462 −277
Merged

refactor(cli): add command registry as single metadata source #1446

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d41e89e
refactor(cli): add command registry as single metadata source
Wibias Aug 11, 2026
3562810
test(cli): require every registry entry name directly in the switch
Wibias Aug 11, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
279 changes: 2 additions & 277 deletions src/cli/help.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,285 +1,10 @@
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import { findCommand } from "./registry";

const repoRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta.url)));

type HelpEntry = {
usage: string;
summary: string;
details?: string[];
};

const helpEntries: Record<string, HelpEntry> = {
init: { usage: "ocx init", summary: "Interactive setup for providers and Codex config injection." },
setup: { usage: "ocx setup", summary: "Interactive setup for providers and Codex config injection (alias of init)." },
start: { usage: "ocx start [--port <port>]", summary: "Start the proxy server and sync models to Codex." },
stop: { usage: "ocx stop", summary: "Stop the proxy and restore native Codex config." },
restore: {
usage: "ocx restore [back]",
summary: "Restore native Codex config without stopping the proxy; `restore back` re-points codex at the running proxy.",
},
eject: {
usage: "ocx eject [back]",
summary: "Restore native Codex config without stopping the proxy; `eject back` re-points codex at the running proxy.",
},
"recover-history": {
usage: "ocx recover-history --legacy-openai",
summary: "Explicitly recover pre-backup syncResumeHistory rows.",
},
uninstall: {
usage: "ocx uninstall",
summary: "Remove service/shim/config and restore native Codex.",
details: [
"Alias: ocx remove",
"Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
],
},
remove: {
usage: "ocx remove",
summary: "Remove service/shim/config and restore native Codex.",
details: [
"Alias of: ocx uninstall",
"Config cleanup requires ownership metadata created by a fresh install; legacy or shared directories are left in place.",
],
},
service: {
usage: "ocx service [install|start|stop|status|uninstall|remove]",
summary: "Run as a background service.",
details: [
"With no subcommand, installs/updates and starts the background service.",
"Use `ocx service status` to see diagnostics and log paths.",
],
},
"codex-shim": {
usage: "ocx codex-shim <install|status|uninstall|remove>",
summary: "Auto-start the proxy when `codex` launches.",
details: ["Use `remove` as an alias for `uninstall`."],
},
tray: {
usage: "ocx 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: "ocx ensure", summary: "Ensure the proxy is running and Codex config/cache are current." },
sync: {
usage: "ocx 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: "ocx 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: "ocx status", summary: "Check proxy server status." },
doctor: { usage: "ocx doctor", summary: "Diagnose environment/network issues (paths, WSL /mnt, proxy env, ChatGPT reachability)." },
debug: {
usage: "ocx 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: ocx debug provider on | off | status | reset | logs [-f]",
"Usage JSONL: ocx debug usage on | off | status | reset | logs [-f]",
"Env default: OCX_DEBUG=1 (legacy OCX_DEBUG_FRAMES still works)",
],
},
login: { usage: "ocx login <provider>", summary: "OAuth or API-key login for a provider." },
logout: { usage: "ocx logout <provider>", summary: "Remove a stored provider login." },
gui: { usage: "ocx gui", summary: "Open the opencodex dashboard." },
update: {
usage: "ocx update [--tag latest|preview]",
summary: "Update opencodex. Preview installs stay on the preview tag unless overridden.",
},
provider: {
usage: "ocx 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 `ocx provider --help` for full usage and examples.",
],
},
account: {
usage: "ocx 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: "ocx 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: "ocx model <subcommand>",
summary: "Alias of ocx models.",
},
combo: {
usage: "ocx combo <list|show|set|remove> ...",
summary: "Manage combo failover and round-robin virtual models.",
details: ["Alias hierarchy: ocx route combo ...", "Use --targets provider/model[:weight],provider/model[:weight]."],
},
route: {
usage: "ocx route combo <list|show|set|remove> ...",
summary: "Manage routing features; combo is currently the supported routing resource.",
},
agent: {
usage: "ocx agent <status|injection|effort|subagents|fallback|sidecar> ...",
summary: "Manage headless multi-agent, roster, effort, injection, and sidecar settings.",
},
observe: {
usage: "ocx observe <logs|usage|storage|memory|debug|claude-inbound|injection> ...",
summary: "Inspect proxy requests, usage, storage, memory, and debug data.",
},
logs: { usage: "ocx logs [filters] [--follow] [--json|--jsonl]", summary: "Alias of ocx observe logs." },
usage: { usage: "ocx usage [--range <7d|30d|all>] [--surface <all|codex|claude|grok>] [--json]", summary: "Alias of ocx observe usage." },
storage: { usage: "ocx storage [--json]", summary: "Alias of ocx observe storage." },
memory: { usage: "ocx memory [--json]", summary: "Alias of ocx observe memory." },
access: {
usage: "ocx access <key|endpoints|models|test> ...",
summary: "Manage OpenCodex admission API keys and inspect external endpoints.",
},
"api-key": { usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
export: {
usage: "ocx 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 — ocx never writes your real client config.",
],
},
grok: { usage: "ocx grok <status|exclude|include|set|clear|apply> ...", summary: "Manage and apply the Grok Build model fence." },
integration: { usage: "ocx integration <claude|grok|client> ...", summary: "Manage supported client integrations." },
system: {
usage: "ocx system <status|settings|startup|diagnostics|sync|update> ...",
summary: "Manage headless runtime settings, startup, sync, diagnostics, and updates.",
},
config: {
usage: "ocx config <show|get|set|unset|validate|export|import> ...",
summary: "Inspect and safely modify validated OpenCodex configuration.",
details: ["Secrets are masked by show/get. Import requires --yes and validates before writing."],
},
claude: {
usage: "ocx 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:",
" ocx claude desktop [apply] Save and apply the four-family profile",
" ocx claude desktop show [--json] Show routes, families, and defaults",
" ocx claude desktop move <route> <family> [--default]",
" ocx claude desktop default <family> <route|none>",
" ocx claude desktop export <path|-> Export versioned JSON (`-` = stdout)",
" ocx 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: ocx claude config <status|set> ...",
],
},
opencode: {
usage: "ocx 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 as opencodex/<provider>/<model>.",
"Stop using `ocx opencode` and plain `opencode` behaves exactly as before.",
],
},
restart: {
usage: "ocx restart",
summary: "Stop the proxy and restart it (background). Equivalent to stop + ensure.",
},
v2: {
usage: "ocx 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: "ocx health [--json]",
summary: "Check proxy health. Exits 0 if healthy, 1 otherwise.",
details: ["Use --json for structured output: {ok, pid, port}."],
},
ready: {
usage: "ocx 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.",
],
},
lab: {
usage: "ocx lab <status|verdicts|subjects|subject|observations|events|event|artifacts|artifact|catalog> [options] [--json]",
summary: "Read-only Compatibility Lab projection inspection (local SQLite; no daemon).",
details: [
"status Projection availability, schema versions, and row counts.",
"verdicts Paginated derived compatibility verdicts with filters.",
"subjects List subjects; subject <id> returns one typed subject.",
"observations Paginated observation rows from the projection.",
"events Event history; event <id> returns one safe typed event.",
"artifacts Artifact metadata only (no content download).",
"catalog Packaged protocol/live scenario catalog metadata.",
"Reads never rebuild the projection, trigger probes, or require the proxy.",
],
},
};

function packageVersion(): string {
const raw = readFileSync(join(repoRoot, "package.json"), "utf8");
const parsed = JSON.parse(raw) as { version?: unknown };
Expand Down Expand Up @@ -352,7 +77,7 @@ export function hasHelpFlag(values: string[]): boolean {
}

export function printSubcommandUsage(name: string | undefined): void {
const entry = name ? helpEntries[name] : undefined;
const entry = name ? findCommand(name) : undefined;
if (!entry) {
console.error(`Unknown command: ${name ?? ""}`.trim());
printUsage();
Expand Down
Loading
Loading