@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
344 lines (342 loc) • 39 kB
text/typescript
import type { Capability } from "./capability-types";
/** Existing provider/model handlers; local configuration operations deliberately have no routes. */
export const PROVIDER_MODEL_CAPABILITIES: readonly Capability[] = [
{
command: ["provider","add"],
summary: "Add a provider locally or explicitly to the running proxy.",
usage: "ocx provider add <name> [--adapter <id>] [--base-url <url>] [--responses-path <path>] [--auth-mode <key|forward|oauth|local>] [--api-key <key>] [--api-key-transport <x-api-key|bearer>] [--default-model <id>] [--model <id> --text-only] [--google-tool-schema-policy <compatible|reject-lossy>] [--allow-private-network] [--set-default] [--force] [--sync | --live] [--json]",
routes: [{"method":"GET","path":"/api/providers"},{"method":"GET","path":"/api/provider-presets"},{"method":"POST","path":"/api/providers"}],
mutates: true,
json: "envelope",
flags: [{"name":"--adapter","value":"string","summary":"Required for a provider absent from the registry."},{"name":"--base-url","value":"string","summary":"Upstream URL; required for an unregistered provider."},{"name":"--api-key","value":"string","summary":"Legacy argv credential input; prefer the human-operated stdin account add-key workflow."},{"name":"--api-key-transport","value":"string","summary":"x-api-key or bearer."},{"name":"--default-model","value":"string","summary":"Default upstream model ID."},{"name":"--model","value":"string","summary":"Model for --text-only; requires that flag."},{"name":"--text-only","value":"boolean","summary":"Declare text-only input for --model or the default model."},{"name":"--google-tool-schema-policy","value":"string","summary":"Google adapter: compatible or reject-lossy."},{"name":"--allow-private-network","value":"boolean","summary":"Permit a private upstream network."},{"name":"--set-default","value":"boolean","summary":"Also select this provider as default."},{"name":"--force","value":"boolean","summary":"Replace an existing provider."},{"name":"--sync","value":"boolean","summary":"Local only: perform requested Codex sync, including in JSON mode; saved-but-unsynced failures remain nonzero."},{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."},{"name":"--live","value":"boolean","summary":"Use the selected running proxy; omission retains local configuration behavior."},{"name":"--responses-path","value":"string","summary":"Relative upstream Responses path; no scheme, query or fragment."},{"name":"--auth-mode","value":"string","summary":"Explicit key, forward, oauth or local auth mode."}],
details: ["Without --live, saves local configuration; --sync reports its actual disposition and needsSync, never fabricated client application. --live cannot be combined with --sync.","Live add reads the target roster and presets. An observed existing row requires --force; POST remains upsert, so the preflight is not atomic create-only protection.","Canonical OpenAI uses the target preset unchanged; transport/auth/model overrides are refused in live add. No local registry fallback when a needed target preset is missing.","Keep real credentials out of argv and agent transcripts; this does not authorize credential capture."],
},
{
command: ["provider", "show"], summary: "Inspect one locally configured provider.",
usage: "ocx provider show <name> [--json]", routes: [], mutates: false, json: "envelope",
flags: [{ name: "--json", value: "boolean", summary: "Emit the local provider view." }],
details: ["Reads local config; masks API-key and key-pool fields. This is not a live provider read or a general secret-export interface."],
},
{
command: ["provider","remove"],
summary: "Remove a local provider or explicitly delete it from the running proxy.",
usage: "ocx provider remove <name> [--json]; ocx provider remove <name> --live --yes [--json]",
routes: [{"method":"DELETE","path":"/api/providers"}],
mutates: true,
json: "envelope",
flags: [{"name":"--live","value":"boolean","summary":"Use the selected running proxy; omission retains local configuration behavior."},{"name":"--yes","value":"boolean","summary":"Required with --live for provider and dependent custom-model/account cleanup."},{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."}],
details: ["Local removal preserves its existing refusal for the current default and has no --yes option.","Live removal uses one server DELETE. The server can choose a replacement default and clean custom models, context caps and OAuth accounts; dependency/last-provider refusals stay authoritative.","No local fallback, multi-step deletion or automatic retry. A saved result with failed catalog convergence exits nonzero without claiming rollback."],
},
{
command: ["provider","set-default"],
summary: "Select the default provider locally or explicitly on the running proxy.",
usage: "ocx provider set-default <name> [--live] [--json]",
routes: [{"method":"PATCH","path":"/api/providers"}],
mutates: true,
json: "envelope",
flags: [{"name":"--live","value":"boolean","summary":"Use the selected running proxy; omission retains local configuration behavior."},{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."}],
details: ["Omission of --live retains local save/no-op semantics. Live sends only setDefault:true; disabled/unknown providers are refused by the server. This operation does not claim client synchronization."],
},
{
command: ["provider","edit"],
summary: "Patch an existing provider through the running proxy.",
usage: "ocx 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>] [--retain-models <id,id|->] [--model <id> --text-only] [--xai-chat <on|off>] [--allow-private-network <on|off>] [--model-context-tier <model=default|long_context>] [--upstream-http-version <http1.1|->] [--fast <on|off>] [--context-window <tokens|->] [--json]",
routes: [{"method":"PATCH","path":"/api/providers"}],
mutates: true,
json: "payload",
flags: [{"name":"--adapter","value":"string","summary":"Adapter ID."},{"name":"--base-url","value":"string","summary":"Upstream URL."},{"name":"--default-model","value":"string","summary":"Model ID; - clears."},{"name":"--auth-mode","value":"string","summary":"key, forward, oauth, local; - clears."},{"name":"--note","value":"string","summary":"Note; - clears."},{"name":"--api-key-transport","value":"string","summary":"x-api-key or bearer; - clears."},{"name":"--headers","value":"string","summary":"JSON object; - or JSON null clears."},{"name":"--enabled","value":"string","summary":"on or off."},{"name":"--live-models","value":"string","summary":"on or off."},{"name":"--retain-models","value":"string","summary":"Comma-separated IDs; - clears with null."},{"name":"--model","value":"string","summary":"Requires --text-only."},{"name":"--text-only","value":"boolean","summary":"Requires --model; declare text-only input."},{"name":"--xai-chat","value":"string","summary":"xai only: on uses Chat, off opts into Responses."},{"name":"--allow-private-network","value":"string","summary":"on or off."},{"name":"--model-context-tier","value":"string","summary":"Repeatable github-copilot model=default or model=long_context."},{"name":"--json","value":"boolean","summary":"Emit the management receipt."},{"name":"--upstream-http-version","value":"string","summary":"http1.1 pins HTTP/1.1; - clears the override."},{"name":"--fast","value":"string","summary":"on or off; false is an explicit edit."},{"name":"--context-window","value":"string","summary":"Positive safe integer provider context limit; - clears, zero is invalid."}],
details: ["At least one edit is required; only supplied fields are patched. update is an existing alias. Use provider show only for local state, not as proof of the live write.","Management errors use safe fixed provider diagnostics; catalog failures retain the saved receipt and a nonzero exit."],
},
{
command: ["provider", "test"], summary: "Probe discovery connectivity or explicitly test one model completion.",
usage: "ocx provider test <name> [--model <id> [--yes]] [--json]",
routes: [{ method: "POST", path: "/api/providers/test" }, { method: "POST", path: "/api/providers/test-completion" }], mutates: true, json: "payload",
flags: [{ name: "--model", value: "string", summary: "Run one bounded completion for this model instead of discovery." }, { name: "--yes", value: "boolean", summary: "Confirm completion quota/cost; requires --model. Mandatory with --json or non-interactive input." }, { name: "--json", value: "boolean", summary: "Emit the probe result; completion warnings go to stderr." }],
details: ["Without --model, discovery behavior is unchanged; static catalogs can return applicable:false. Completion tests print a quota/cost warning and require a default-No terminal confirmation or --yes; cancellation exits 1 without a request.", "Completion output includes TTFT, total latency, upstream/wire model metadata and comparison. Metadata is not proof of model identity; mismatch still exits 0. Failed tests exit 1; non-applicable results exit 0."],
},
{
command: ["provider", "quota"], summary: "Read provider quota reports, optionally refreshing them.",
usage: "ocx provider quota [--refresh] [--json]", routes: [{ method: "GET", path: "/api/provider-quotas" }], mutates: false, json: "payload",
flags: [{ name: "--refresh", value: "boolean", summary: "Request refresh=1; may contact providers and update cached observations." }, { name: "--json", value: "boolean", summary: "Emit the quota report." }],
details: ["Reads quota observations without changing operator settings. Cache misses may probe upstream even without --refresh; --refresh bypasses the cache and updates observations. This GET is not the POST account-refresh operation."],
},
{
command: ["provider", "presets"], summary: "Read provider presets from the running proxy.",
usage: "ocx provider presets [--json]", routes: [{ method: "GET", path: "/api/provider-presets" }], mutates: false, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit the preset payload." }],
},
{
command: ["provider", "account-mode"], summary: "Set OpenAI Codex account routing to pool or direct.",
usage: "ocx provider account-mode <pool|direct> [--json]", routes: [{ method: "PATCH", path: "/api/providers" }], mutates: true, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit the management receipt." }],
details: ["Patches codexAccountMode on provider openai; this does not switch the physical Codex login."],
},
{
command: ["provider", "selected"], summary: "Read or replace one provider's selected model allowlist.",
usage: "ocx provider selected <name> [--set <id,id...>|--clear] [--json]",
routes: [{ method: "GET", path: "/api/selected-models" }, { method: "PUT", path: "/api/selected-models" }], mutates: true, json: "envelope",
flags: [{ name: "--set", value: "string", summary: "Replace with comma-separated upstream IDs." }, { name: "--clear", value: "boolean", summary: "Clear the allowlist to show all; exclusive with --set." }, { name: "--json", value: "boolean", summary: "Emit the selected view or receipt." }],
details: ["Without a mutation flag this reads only. --clear sends models:[], not a model named -.", "Read JSON is the CLI projection {provider, selected: string[], available: string[]}, not the API's provider-keyed maps; missing entries become empty arrays. --set/--clear JSON returns the server's write receipt unchanged."],
},
{
command: ["provider", "import-cc-switch"], summary: "Preview, apply, or restore keyless CC-Switch provider entries locally.",
usage: "ocx provider import-cc-switch [--source <cc-switch.db|config.json>] [--provider <id>]... [--apply | --restore] [--allow-private-network] [--json]",
routes: [], mutates: true, json: "payload",
flags: [{ name: "--source", value: "string", summary: "CC-Switch SQLite database or legacy JSON file; required for preview and apply." }, { name: "--provider", value: "string", summary: "Repeatable source ID or target provider name filter." }, { name: "--apply", value: "boolean", summary: "Write eligible keyless provider entries and record a rollback journal; requires a stopped proxy." }, { name: "--restore", value: "boolean", summary: "Remove unedited keyless providers recorded by the active import journal; requires a stopped proxy." }, { name: "--allow-private-network", value: "boolean", summary: "Permit loopback or private-network provider base URLs." }, { name: "--json", value: "boolean", summary: "Emit the preview, apply, or restore report as JSON." }],
details: ["Projects values only from an explicit allowlist of non-secret metadata fields (provider IDs, app types, base URLs, wire dialects, and default models); source and embedded-config bytes are read transiently while secret fields, free-text names, and TOML comments are skipped at the byte level and never decoded into strings, written, or logged, and transient byte buffers are zeroed in finally.", "Only import from a trusted local CC-Switch source: apply prints every imported ID, model, and destination URL before writing, refuses SQLite hard links (nlink > 1) and non-empty -wal/-journal sidecars until CC-Switch is closed, and opens sources read-only with O_NOFOLLOW|O_NONBLOCK descriptor checks; restore inspects auth.json read-only at the byte level and retains any provider that was edited, selected as defaultProvider, or referenced by routing, combos, fallback policy, OAuth accounts, or API keys."],
},
{
command: ["models", "list"], summary: "List local configured and router-known models.",
usage: "ocx models list [--provider <name>] [--json]", routes: [], mutates: false, json: "envelope",
flags: [{ name: "--provider", value: "string", summary: "Limit to a configured provider." }, { name: "--json", value: "boolean", summary: "Emit models and the local-catalog note." }],
details: ["A bare models invocation is equivalent. Includes saved IDs, registry seeds, custom models and this process's discovery cache; use models live for the running catalog."],
},
{
command: ["models","add"],
summary: "Add a custom model locally or explicitly on the running proxy.",
usage: "ocx models add <provider> <modelId> [--display-name <name>] [--context-window <tokens>] [--modalities <text,image,audio>] [--reasoning-efforts <levels|->] [--default-reasoning-effort <level|->] [--live] [--json]",
routes: [{"method":"POST","path":"/api/custom-models"}],
mutates: true,
json: "envelope",
flags: [{"name":"--display-name","value":"string","summary":"Custom display name without a slash."},{"name":"--context-window","value":"number","summary":"Positive integer token count."},{"name":"--modalities","value":"string","summary":"Comma-separated text, image, audio."},{"name":"--reasoning-efforts","value":"string","summary":"Comma-separated supported levels; - inherits; an empty string declares no reasoning."},{"name":"--default-reasoning-effort","value":"string","summary":"A declared level; - inherits."},{"name":"--live","value":"boolean","summary":"Use the selected running proxy; omission retains local custom-model behavior."},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
details: ["Without --live, saves locally and opportunistically syncs only if a proxy is available. No proxy keeps the save successful with needsSync:true; attempted failure/refusal is nonzero. JSON is one safe save/sync receipt.","Live add sends the same metadata to the server and returns its stored custom identity plus catalog outcome. Empty reasoning ladder differs from omitted/inherited metadata. No local fallback."],
},
{
command: ["models","remove"],
summary: "Remove an exact custom model locally or on the selected proxy.",
usage: "ocx models remove <customId|provider/modelId> [--yes] [--live] [--json]",
routes: [{"method":"GET","path":"/api/custom-models"},{"method":"DELETE","path":"/api/custom-models/{id}"}],
mutates: true,
json: "envelope",
flags: [{"name":"--yes","value":"boolean","summary":"Required for live or JSON deletion; local text mode retains its interactive confirmation."},{"name":"--live","value":"boolean","summary":"Use the selected running proxy; omission retains local custom-model behavior."},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
details: ["Live selection uses the complete target custom roster and an exact stored ID or unambiguous provider/raw selector. Display labels, ID prefixes and encoded/raw collisions never choose a deletion target.","One encoded stored-ID DELETE; no alternative-ID retry, local fallback or revision protection. Local JSON saves/syncs retain the same opportunistic policy as add."],
},
{
command: ["models", "list-custom"], summary: "List locally stored custom model definitions and their IDs.",
usage: "ocx models list-custom [--json]", routes: [], mutates: false, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit the local customModels array with full IDs." }],
details: ["Reads local configuration, not the management API."],
},
{
command: ["models", "live"], summary: "Read the running proxy's model catalog.",
usage: "ocx models live [--provider <name>] [--free-only] [--json]", routes: [{ method: "GET", path: "/api/models" }], mutates: false, json: "payload",
flags: [{ name: "--provider", value: "string", summary: "Filter returned rows by provider." }, { name: "--free-only", value: "boolean", summary: "Include only rows explicitly classified free." }, { name: "--json", value: "boolean", summary: "Emit the filtered catalog array." }],
},
{
command: ["models", "edit"], summary: "Edit a custom model by its definition ID through the proxy.",
usage: "ocx models edit <custom-id> [--model-id <id>] [--display-name <name|->] [--context-window <tokens|0>] [--modalities <text,image,audio|->] [--reasoning-efforts <levels|->] [--default-reasoning-effort <level|->] [--json]",
routes: [{ method: "PUT", path: "/api/custom-models/{id}" }], mutates: true, json: "payload",
flags: [
{ name: "--model-id", value: "string", summary: "Upstream model ID." },
{ name: "--display-name", value: "string", summary: "Custom definition name; - clears." },
{ name: "--context-window", value: "number", summary: "Safe token count; 0 clears. Unlike models set, - is invalid here." },
{ name: "--modalities", value: "string", summary: "Comma-separated modalities; - sends an empty list." },
{ name: "--reasoning-efforts", value: "string", summary: "Comma-separated levels; - inherits (null), empty string stores an empty ladder." },
{ name: "--default-reasoning-effort", value: "string", summary: "Default effort; - clears with null." },
{ name: "--json", value: "boolean", summary: "Emit the management receipt." },
],
details: ["At least one edit is required. Operand is the custom definition ID from list-custom, not a provider/model selector. Discovered-model display-name overrides are a different resource."],
},
{
command: ["models", "enable"], summary: "Enable one routed or native catalog model.",
usage: "ocx models enable <provider/model|native-model> [--native] [--json]", routes: [{ method: "PUT", path: "/api/model-visibility" }], mutates: true, json: "payload",
flags: [{ name: "--native", value: "boolean", summary: "Treat the whole selector as a native OpenAI model ID." }, { name: "--json", value: "boolean", summary: "Emit the visibility receipt." }],
},
{
command: ["models", "disable"], summary: "Disable one routed or native catalog model.",
usage: "ocx models disable <provider/model|native-model> [--native] [--json]", routes: [{ method: "PUT", path: "/api/model-visibility" }], mutates: true, json: "payload",
flags: [{ name: "--native", value: "boolean", summary: "Treat the whole selector as a native OpenAI model ID." }, { name: "--json", value: "boolean", summary: "Emit the visibility receipt." }],
},
{
command: ["models", "provider"], summary: "Enable or disable all catalog rows for a provider.",
usage: "ocx models provider <name> <on|off> [--json]", routes: [{ method: "GET", path: "/api/models" }, { method: "PUT", path: "/api/model-visibility" }], mutates: true, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit the visibility receipt." }],
details: ["Reads targets from the live catalog first; refuses a provider without available models."],
},
{
command: ["models", "selected"], summary: "Read or replace a provider's selected model allowlist.",
usage: "ocx models selected <provider> [--set <id,id...>|--clear] [--json]", routes: [{ method: "GET", path: "/api/selected-models" }, { method: "PUT", path: "/api/selected-models" }], mutates: true, json: "envelope",
flags: [{ name: "--set", value: "string", summary: "Replace the allowlist with comma-separated IDs." }, { name: "--clear", value: "boolean", summary: "Send an empty list to show all; exclusive with --set." }, { name: "--json", value: "boolean", summary: "Emit the selected view or receipt." }],
details: ["Without --set or --clear this only reads. A literal - is not the clear spelling.", "Read JSON is the CLI projection {provider, selected: string[], available: string[]}, not the API's provider-keyed maps; missing entries become empty arrays. --set/--clear JSON returns the server's write receipt unchanged."],
},
{
command: ["models", "preset", "show"], summary: "Inspect shipped model presets and applied versions.",
usage: "ocx models preset show [--provider <name>] [--json]", routes: [{ method: "GET", path: "/api/model-presets" }], mutates: false, json: "payload",
flags: [{ name: "--provider", value: "string", summary: "Project a single provider's preset." }, { name: "--json", value: "boolean", summary: "Emit the preset view." }],
},
{
command: ["models", "preset", "apply"], summary: "Apply a provider's curated model preset or show all models.",
usage: "ocx models preset apply <provider> [--all] [--json]", routes: [{ method: "PUT", path: "/api/model-presets" }], mutates: true, json: "payload",
flags: [{ name: "--all", value: "boolean", summary: "Use mode all instead of preset." }, { name: "--json", value: "boolean", summary: "Emit the application receipt." }],
details: ["An empty preset match preserves the previous selection and reports fallback; do not interpret it as successful narrowing."],
},
{
command: ["models", "new-policy"], summary: "Read or set the policy for newly discovered models.",
usage: "ocx models new-policy [on|off|admit] [--provider <name>] [--json]", routes: [{ method: "GET", path: "/api/model-discovery" }, { method: "PUT", path: "/api/model-discovery" }], mutates: true, json: "payload",
flags: [{ name: "--provider", value: "string", summary: "Scope the read/write to a provider; omitted means global." }, { name: "--json", value: "boolean", summary: "Emit the policy view or receipt." }],
details: ["No state operand means read only. Writes on, off or admit; admit appends new arrivals to a provider's custom selectedModels and never widens a preset-derived selection. No inherit/clear operand is implemented."],
},
{
command: ["models", "new-arrivals"], summary: "Read recent model discoveries.",
usage: "ocx models new-arrivals [--json]", routes: [{ method: "GET", path: "/api/model-discovery" }], mutates: false, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit recentArrivals grouped by provider." }],
},
{
command: ["models", "discover"], summary: "Re-fetch one provider's live model list now and report new arrivals.",
usage: "ocx models discover <provider> [--json]", routes: [{ method: "POST", path: "/api/model-discovery/refresh" }], mutates: true, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit discovery status, newArrivals and recentArrivals." }],
details: ["Refreshes one provider's model list. New models follow the configured new-model policy. If discovery is already running for that provider, the route returns HTTP 409 (`discovery_in_progress`). During cooldown it returns the recorded failure. Providers with liveModels off report applicable:false."],
},
{
command: ["models", "context", "status"], summary: "Read routed-provider context caps.",
usage: "ocx models context status [--json]", routes: [{ method: "GET", path: "/api/provider-context-caps" }], mutates: false, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit context settings." }],
},
{
command: ["models", "context", "value"], summary: "Set the default routed-provider context cap value.",
usage: "ocx models context value <tokens> [--set-all] [--json]", routes: [{ method: "PUT", path: "/api/provider-context-caps" }], mutates: true, json: "payload",
flags: [{ name: "--set-all", value: "boolean", summary: "Also apply the value to every routed provider." }, { name: "--json", value: "boolean", summary: "Emit the context receipt." }],
details: ["Tokens must be a positive safe integer; separators _ and , are accepted. Without --set-all only the default for future toggles changes."],
},
{
command: ["models", "context", "provider"], summary: "Toggle one provider's context cap, optionally choosing its value.",
usage: "ocx models context provider <provider> <on|off> [--value <tokens>] [--json]", routes: [{ method: "PUT", path: "/api/provider-context-caps" }], mutates: true, json: "payload",
flags: [{ name: "--value", value: "number", summary: "Positive integer; only valid with on." }, { name: "--json", value: "boolean", summary: "Emit the context receipt." }],
details: ["off disables this provider's cap; --value is not a global value change."],
},
{
command: ["models", "context", "all"], summary: "Enable or disable caps for all routed providers.",
usage: "ocx models context all <on|off> [--json]", routes: [{ method: "PUT", path: "/api/provider-context-caps" }], mutates: true, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit the context receipt." }],
},
{
command: ["models", "shadow", "status"], summary: "Read shadow-call settings.",
usage: "ocx models shadow status [--json]", routes: [{ method: "GET", path: "/api/shadow-call-settings" }], mutates: false, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit shadow-call settings." }],
},
{
command: ["models", "shadow", "set"], summary: "Set the shadow-call model or enabled state.",
usage: "ocx models shadow set [model|-] [--enabled <on|off>] [--json]", routes: [{ method: "PUT", path: "/api/shadow-call-settings" }], mutates: true, json: "payload",
flags: [{ name: "--enabled", value: "string", summary: "on or off; takes a value." }, { name: "--json", value: "boolean", summary: "Emit the settings receipt." }],
details: ["At least a model or --enabled is required; - clears the model with an empty string. Enabling shadow calls can cause subsequent inference calls."],
},
{
command: ["models", "auto-review", "status"], summary: "Read the global auto-review model and enabled state.",
usage: "ocx models auto-review status [--json]", routes: [{ method: "GET", path: "/api/auto-review-settings" }], mutates: false, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit auto-review settings." }],
},
{
command: ["models", "auto-review", "set"], summary: "Set the global auto-review model or enabled state.",
usage: "ocx models auto-review set [model|-] [--enabled <on|off>] [--json]", routes: [{ method: "PUT", path: "/api/auto-review-settings" }], mutates: true, json: "payload",
flags: [{ name: "--enabled", value: "string", summary: "on or off; takes a value." }, { name: "--json", value: "boolean", summary: "Emit the settings receipt." }],
details: ["At least a model or --enabled is required; - clears the model with an empty string. Human output points to ocx sync when a catalog refresh can be retried and asks operators to resolve a failed refresh before syncing."],
},
{
command: ["alias", "list"], summary: "Read provider and model aliases.",
usage: "ocx alias list [--json]", routes: [{ method: "GET", path: "/api/aliases" }], mutates: false, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit alias maps and provenance." }],
},
{
command: ["alias", "set"], summary: "Assign a provider or upstream model alias.",
usage: "ocx alias set <provider|provider/native-model-id> <alias> [--json]", routes: [{ method: "PUT", path: "/api/providers/{provider}/alias" }, { method: "PUT", path: "/api/providers/{provider}/model-aliases" }], mutates: true, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit the alias receipt." }],
details: ["The first slash separates provider from the complete upstream model ID."],
},
{
command: ["alias", "rm"], summary: "Clear a provider or model alias.",
usage: "ocx alias rm <provider|provider/native-model-id> [--json]", routes: [{ method: "PUT", path: "/api/providers/{provider}/alias" }, { method: "PUT", path: "/api/providers/{provider}/model-aliases" }], mutates: true, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit the alias removal receipt." }],
details: ["Provider clear sends alias:null; model clear sends remove:[modelId]."],
},
{
command: ["alias", "defaults"], summary: "Toggle built-in model aliases globally or for a provider.",
usage: "ocx alias defaults <on|off> [--provider <name>] [--json]", routes: [{ method: "PUT", path: "/api/default-aliases" }], mutates: true, json: "payload",
flags: [{ name: "--provider", value: "string", summary: "Limit the toggle to one provider." }, { name: "--json", value: "boolean", summary: "Emit the alias settings receipt." }],
},
{
command: ["alias", "template", "set"], summary: "Set a provider's opt-in alias template for models without an alias.",
usage: "ocx alias template set <provider> <template> [--json]", routes: [{ method: "PUT", path: "/api/providers/{provider}/alias-template" }], mutates: true, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit the receipt with the generated and skipped preview." }],
details: ["Only the literal {providerAlias} and {modelBasename} placeholders are allowed, and {modelBasename} is required. Aliases are derived when models resolve and never written to config. Manual and built-in aliases win; a generated name that collides with anything already claimed is skipped, never renamed."],
},
{
command: ["alias", "template", "rm"], summary: "Remove a provider's alias template; its generated aliases disappear at once.",
usage: "ocx alias template rm <provider> [--json]", routes: [{ method: "PUT", path: "/api/providers/{provider}/alias-template" }], mutates: true, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit the receipt." }],
},
{
command: ["alias", "template", "show"], summary: "Read configured alias templates.",
usage: "ocx alias template show [<provider>] [--json]", routes: [{ method: "GET", path: "/api/aliases" }], mutates: false, json: "payload",
flags: [{ name: "--json", value: "boolean", summary: "Emit the template map, or one provider's template." }],
},
{
command: ["provider","pacing"],
usage: "ocx provider pacing <name> [--json]; ocx provider pacing <name> [--enabled <on|off>] [--rpm <number>] [--min-interval-ms <integer>] [--max-concurrent <integer>] [--json]; ocx provider pacing <name> --file <FILE|-> [--json]",
summary: "Read request pacing rules/status or explicitly replace the configured block.",
routes: [{"method":"GET","path":"/api/config"},{"method":"GET","path":"/api/provider-request-pacing"},{"method":"PATCH","path":"/api/providers"}],
flags: [{"name":"--enabled","value":"string","summary":"on or off; numeric changes never implicitly enable."},{"name":"--rpm","value":"number","summary":"Fractional requests per minute, from 1/60 to 60000."},{"name":"--min-interval-ms","value":"number","summary":"Positive integer delay, at most 3600000."},{"name":"--max-concurrent","value":"number","summary":"Positive integer concurrency cap."},{"name":"--file","value":"string","summary":"Complete rules JSON, or - for bounded non-TTY stdin; exclusive with scalar flags."},{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."}],
mutates: true,
json: "envelope",
details: ["Read returns {provider,rules,status}; rules:null means no configured block, not an unavailable target.","Scalar edits preserve model rules observed from the pinned config; PATCH replaces the block and can overwrite an intervening edit. Use snapshot/apply for public-baseline CAS.","File mode validates a complete non-null rules block and writes without a prior rule read. Pacing limits reject zero."],
},
{
command: ["provider","snapshot"],
usage: "ocx provider snapshot [--json]",
summary: "Read the non-secret provider editor snapshot from the running proxy.",
routes: [{"method":"GET","path":"/api/config"}],
flags: [{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."}],
mutates: false,
json: "envelope",
details: ["Emits exactly {defaultProvider,providers}, validating the canonical editor DTO after removing only GUI display markers. Unexpected secret/unknown fields fail closed.","Save this JSON as the baseline for apply; it is not raw config export and carries no cross-invocation target identity. Use the intended host/context."],
},
{
command: ["provider","apply"],
usage: "ocx provider apply --baseline <FILE|-> --file <FILE|-> [--yes] [--json]",
summary: "Apply a provider editor document with the server public-baseline conflict check.",
routes: [{"method":"PUT","path":"/api/providers"}],
flags: [{"name":"--baseline","value":"string","summary":"Original non-secret provider snapshot.","required":true},{"name":"--file","value":"string","summary":"Edited next snapshot.","required":true},{"name":"--yes","value":"boolean","summary":"Required for removals or renames within the submitted provider roster."},{"name":"--json","value":"boolean","summary":"Emit the operation receipt as JSON."}],
mutates: true,
json: "payload",
details: ["Both documents must contain exactly defaultProvider and providers, with no credential/derived/unknown fields. At most one source may be stdin; each input and the complete serialized body are bounded to 4 MiB, with a 30-second read deadline.","Sends one {baseline,next} PUT. Stale baseline is exit 5; no automatic refresh, rebase, retry or local fallback.","Batch removal preserves the server batch contract and does not promise single-provider DELETE OAuth cleanup. Saved-but-unconverged catalog outcomes remain visible and nonzero."],
},
{
command: ["models","display-name"],
usage: "ocx models display-name <provider/raw-model> (--set <text> | --clear) [--json]",
summary: "Set or clear one raw upstream model display-name override.",
routes: [{"method":"PUT","path":"/api/providers/{provider}/model-display-names"}],
flags: [{"name":"--set","value":"string","summary":"Nonblank display label; exclusive with --clear."},{"name":"--clear","value":"boolean","summary":"Send null to clear the override."},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
mutates: true,
json: "envelope",
details: ["Split only the first provider slash; the remaining model ID is raw upstream identity, not a guessed public alias or encoded suffix.","A recognized saved-but-failed catalog HTTP503 retains its safe receipt and exits1; no retry or rollback claim."],
},
{
command: ["models","order","status"],
usage: "ocx models order status [--json]",
summary: "Read saved picker order, routed candidates and featured state.",
routes: [{"method":"GET","path":"/api/subagent-models"}],
flags: [{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
mutates: false,
json: "envelope",
details: ["Preserves native IDs in saved order. pickerAvailable is routed-only; unknown featured state is not an empty successful roster."],
},
{
command: ["models","order","set"],
usage: "ocx models order set (--models <csv> | --mode <default|alphabetical|provider|most-used>) [--json]",
summary: "Replace the routed picker order with an explicit list or sort mode.",
routes: [{"method":"GET","path":"/api/subagent-models"},{"method":"GET","path":"/api/models"},{"method":"GET","path":"/api/usage"},{"method":"PUT","path":"/api/subagent-models"}],
flags: [{"name":"--models","value":"string","summary":"Complete unique routed candidate permutation, preserving the exact featured prefix; exclusive with --mode."},{"name":"--mode","value":"string","summary":"default clears; alphabetical, provider and most-used compute complete routed orders."},{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
mutates: true,
json: "envelope",
details: ["Manual/preset replacement refuses a native-inclusive saved order until explicit reset/default. It never edits the featured models/force fields.","Manual mode rechecks settings and identities before PUT and refuses observed drift; this is not server CAS. Raw/encoded ambiguities and missing identities refuse before writing.","Most-used reads all/all usage, uses requested model identities and refuses incomplete evidence. Presets retain unranked candidates. A saved receipt does not prove client convergence."],
},
{
command: ["models","order","reset"],
usage: "ocx models order reset [--json]",
summary: "Clear saved picker ordering and its mode.",
routes: [{"method":"PUT","path":"/api/subagent-models"}],
flags: [{"name":"--json","value":"boolean","summary":"Emit the validated command result as JSON."}],
mutates: true,
json: "envelope",
details: ["Sends only pickerOrder:null and pickerOrderMode:null. Explicitly clears native-inclusive order as well; does not change featured models or force selection."],
},
];