From 40e8084b8c10ee86230d9d1f89ddcbbe7d36350e Mon Sep 17 00:00:00 2001 From: Xiangzhe Date: Tue, 18 Aug 2026 17:26:19 -0300 Subject: [PATCH] docs(cli): fix drifts found in the post-relay documentation audit - ENVIRONMENT.md: CLI_ALLOW_CONFIG_WRITES default is true (matches cliRuntime), CLI_QODER_BIN default is qodercli (also in .env.example), CLI_GEMINI_BIN is server-side detection only (omniroute run resolves from PATH) - CLI-TOOLS.md: catalog counts 26 code / 8 agents (adds the missing zcode row), setup targets without auto-discovery list Qwen (not Gemini; Gemini is launch-only), hostSetupCommand only for the six tools with a host recipe, global env block uses GOOGLE_GEMINI_BASE_URL at the root, mention omniroute run as the generic launcher - CLI-INTEGRATIONS.md: manifest aliases, per-target --model wiring (openai/ and omniroute/ prefixes, qwen hard-requires --model), run exit-code contract, gemini child-env scrub notes - CODEX-CLI-CONFIGURATION.md: document omniroute configure codex / run codex - SETUP_GUIDE.md + QUICK-START.md: surface the generic omniroute run launcher - ENVIRONMENT.md: disambiguate OMNIROUTE_SMOKE_API_KEY (canary) from the OMNIROUTE_SMOKE_* CLI smoke-harness variables --- .env.example | 2 +- docs/getting-started/QUICK-START.md | 2 + docs/guides/CLI-INTEGRATIONS.md | 30 +++++++++- docs/guides/CODEX-CLI-CONFIGURATION.md | 11 ++++ docs/guides/SETUP_GUIDE.md | 8 ++- docs/reference/CLI-TOOLS.md | 81 ++++++++++++++------------ docs/reference/ENVIRONMENT.md | 8 +-- 7 files changed, 94 insertions(+), 48 deletions(-) diff --git a/.env.example b/.env.example index 653b82a1a1..8df011088b 100644 --- a/.env.example +++ b/.env.example @@ -761,7 +761,7 @@ NEXT_PUBLIC_ENABLE_SOCKS5_PROXY=true # CLI_CURSOR_BIN=agent # CLI_CLINE_BIN=cline # CLI_CONTINUE_BIN=cn -# CLI_QODER_BIN=qoder +# CLI_QODER_BIN=qodercli # CLI_QWEN_BIN=qwen # CLI_AIDER_BIN=aider # CLI_GOOSE_BIN=goose diff --git a/docs/getting-started/QUICK-START.md b/docs/getting-started/QUICK-START.md index c4b34316c7..d336934436 100644 --- a/docs/getting-started/QUICK-START.md +++ b/docs/getting-started/QUICK-START.md @@ -140,6 +140,8 @@ omniroute launch-codex --model auto You can do this manually via `codex` and command line parameters to specify endpoint and api key, but with the above command, OmniRoute takes care of everything for you. +The same one-command launch works for other CLIs via the generic launcher — `omniroute run ` supports `claude`, `codex`, `aider`, `goose`, `opencode`, `qwen`, and `gemini` (see [CLI Integrations](../guides/CLI-INTEGRATIONS.md)). + 3. The CLI should be sending requests to OmniRoute now. ### Confirm your tool is routing to OmniRoute diff --git a/docs/guides/CLI-INTEGRATIONS.md b/docs/guides/CLI-INTEGRATIONS.md index 7ea32fdb6c..f429b088c6 100644 --- a/docs/guides/CLI-INTEGRATIONS.md +++ b/docs/guides/CLI-INTEGRATIONS.md @@ -14,9 +14,15 @@ OmniRoute (local or remote) and writes the tool's own config file on **your** machine. The API key is referenced by an environment variable wherever the tool supports it. Commands that persist a tool-local environment file are noted below. -There are also two launchers — `omniroute launch` (Claude Code) and -`omniroute launch-codex` (Codex) — that spawn the CLI with the right env injected, -without writing any config at all. +There is also a generic launcher — `omniroute run ` — that spawns +`claude`, `codex`, `aider`, `goose`, `opencode`, `qwen` or `gemini` with the +right env injected, without writing any config at all. Targets and their +aliases come from the canonical manifest `bin/cli/cli-manifest.mjs` +(`claude-code|cc|anthropic`, `codex-cli|openai-codex|openai`, `goose-cli`, +`open-code`, `qwen-code`, `gemini-cli`), and `omniroute completion` offers the +same manifest-derived target words. The legacy per-tool launchers — +`omniroute launch` (Claude Code) and `omniroute launch-codex` (Codex) — remain +available. Provider onboarding is available from the same local/remote context. The API-first commands below keep management authentication separate from provider @@ -87,8 +93,21 @@ Notes on flags (verified in the command source): model auto-discovery: Cline, Kilo, Roo, Goose, Qwen, Aider. Those tools also accept `--yes` for non-interactive runs (which then requires `--model`). `setup-opencode` takes `--model` to set the default top-level model. +- `--model ` on `omniroute run` follows the manifest's per-target wiring + (`bin/cli/cli-manifest.mjs`): **aider** receives `--model openai/` and + **opencode** `--model omniroute/` (the prefix is added only when the id + does not already carry it); **qwen** and **gemini** receive the id verbatim; + **claude** gets it via `ANTHROPIC_MODEL`, **goose** via `GOOSE_MODEL`, and + **codex** via `-c model_providers.omniroute.*` args. **Qwen is the only run + target that hard-requires `--model`** — `omniroute run qwen` without it exits + `2` with an explicit error. - `--port ` — local OmniRoute port (default `20128`, ignored when `--remote` is set). Present on all `setup-*` and both launchers. +- `omniroute run` exit codes: the child CLI's own exit code is propagated + verbatim; `2` = invalid arguments (unsupported target, missing required + `--model`, container guard); `127` = the target binary is not in `PATH`; + `130`/`143`/`129` when the launch is ended by `SIGINT`/`SIGTERM`/`SIGHUP`; + `1` = other runtime launch failure. - The two launchers (`launch`, `launch-codex`) accept `--profile ` to select a profile written by `setup-claude` / `setup-codex`, plus pass-through args for the underlying `claude` / `codex` binary. @@ -251,6 +270,11 @@ Gemini surface (`/v1beta`). `omniroute run gemini` wires that automatically: - a **temporary isolated `GEMINI_CLI_HOME`** whose `.gemini/settings.json` selects `gemini-api-key` auth, so a stored Google OAuth session (Code Assist) never overrides the OmniRoute-directed launch — removed after exit; +- **env hygiene**: the child env is scrubbed of `GOOGLE_API_KEY`, + `GOOGLE_GENAI_USE_VERTEXAI` and `GOOGLE_GENAI_USE_GCA` (which would redirect + auth to Vertex/Code Assist), and `GEMINI_DEFAULT_AUTH_TYPE=gemini-api-key` is + set as a belt-and-suspenders fallback — the other `run` targets get the same + treatment for their own conflicting variables; - `--model ` injection from `--provider`/`--model`. ```bash diff --git a/docs/guides/CODEX-CLI-CONFIGURATION.md b/docs/guides/CODEX-CLI-CONFIGURATION.md index bde7cf0c9b..f8ee1494c7 100644 --- a/docs/guides/CODEX-CLI-CONFIGURATION.md +++ b/docs/guides/CODEX-CLI-CONFIGURATION.md @@ -319,6 +319,17 @@ omniroute launch-codex --remote http://100.x.x.x:20128/v1 --api-key sk-xxx omniroute launch-codex --profile glm52 -- --yolo "fix this bug" ``` +Codex is also a target of the two generic manifest-driven entry points +(`bin/cli/cli-manifest.mjs`): + +```bash +# Interactive model picker → writes ~/.codex/.config.toml (TOML, env_key) +omniroute configure codex + +# Launch codex with the omniroute provider injected via -c flags (no config written) +omniroute run codex +``` + --- ## New Codex CLI features (v0.138–v0.141) diff --git a/docs/guides/SETUP_GUIDE.md b/docs/guides/SETUP_GUIDE.md index 68bf2e8e90..25d9ac9267 100644 --- a/docs/guides/SETUP_GUIDE.md +++ b/docs/guides/SETUP_GUIDE.md @@ -186,9 +186,11 @@ omniroute setup-qwen # ~/.qwen/settings.json + ~/.qwen/.env ``` Each accepts `--remote --api-key ` to configure a local tool against a -**remote** OmniRoute, plus `--dry-run` to preview. The launchers -`omniroute launch` (Claude Code) and `omniroute launch-codex` (Codex) spawn the CLI -with the right env injected, writing no config at all. +**remote** OmniRoute, plus `--dry-run` to preview. To launch a CLI with the right +env injected and no config written at all, use the generic launcher +`omniroute run ` (claude, codex, aider, goose, opencode, qwen, gemini); +the legacy per-tool launchers `omniroute launch` (Claude Code) and +`omniroute launch-codex` (Codex) remain available. For the full table (what each command writes, every flag, local vs remote, base-URL `/v1` conventions), see **[CLI Integrations](./CLI-INTEGRATIONS.md)**. diff --git a/docs/reference/CLI-TOOLS.md b/docs/reference/CLI-TOOLS.md index b9c3deac47..0d208ee515 100644 --- a/docs/reference/CLI-TOOLS.md +++ b/docs/reference/CLI-TOOLS.md @@ -12,8 +12,8 @@ OmniRoute integrates with three categories of CLI tools spread across three dedi | Page | Route | Concept | Count | | -------------- | ----------------------- | ------------------------------------------------------------------------- | ------------ | -| **CLI Code's** | `/dashboard/cli-code` | Coding tools you point at OmniRoute (Client → CLI → OmniRoute → Provider) | 21 | -| **CLI Agents** | `/dashboard/cli-agents` | Autonomous agents you point at OmniRoute (same flow, broader scope) | 6 | +| **CLI Code's** | `/dashboard/cli-code` | Coding tools you point at OmniRoute (Client → CLI → OmniRoute → Provider) | 26 | +| **CLI Agents** | `/dashboard/cli-agents` | Autonomous agents you point at OmniRoute (same flow, broader scope) | 8 | | **ACP Agents** | `/dashboard/acp-agents` | CLIs that OmniRoute spawns as backend via stdio/ACP (reverse flow) | see registry | Legacy routes redirect via 308: `/dashboard/cli-tools` → `/dashboard/cli-code`, `/dashboard/agents` → `/dashboard/acp-agents`. @@ -60,10 +60,14 @@ omniroute setup-goose omniroute setup-qwen omniroute setup-aider Each accepts `--remote --api-key ` (configure a local tool against a remote OmniRoute), `--dry-run` (preview without writing), and `--port`. Tools -without model auto-discovery (Cline, Kilo, Roo, Goose, Aider, Gemini) take -`--model ` (and `--yes` for non-interactive runs). The launchers -`omniroute launch` (Claude Code) and `omniroute launch-codex` (Codex) spawn the CLI -with the right env injected and write no config at all. +without model auto-discovery (Cline, Kilo, Roo, Goose, Aider, Qwen) take +`--model ` (and `--yes` for non-interactive runs). To launch a CLI with the +right env injected and no config written at all, use the generic +`omniroute run ` launcher (claude, codex, aider, goose, opencode, qwen, +gemini — targets and aliases come from `bin/cli/cli-manifest.mjs`); the legacy +per-tool launchers `omniroute launch` (Claude Code) and `omniroute launch-codex` +(Codex) remain available. Gemini CLI is launch-only: it is an `omniroute run` +target but has no `setup-*`/`configure` recipe. > **Full reference:** the master table — what each command writes, every flag, > local vs remote, and which tools want a `/v1` suffix — lives in @@ -86,8 +90,9 @@ the server. See The dashboard's **apply endpoint** (`POST /api/cli-tools/apply`) enforces the same guard: in a container, a write whose target is not bind-mounted from the host answers **`422`** with `containerEphemeralTarget: true`, the safe error -text and a `hostSetupCommand` (e.g. `omniroute setup-opencode`) to run on the -host instead — nothing is written. `dryRun: true` keeps working in container +text and — for the tools with a host recipe (claude, codex, opencode, cline, +kilo, continue) — a `hostSetupCommand` (e.g. `omniroute setup-opencode`) to run +on the host instead; nothing is written. `dryRun: true` keeps working in container mode and returns the generated content + target path without touching disk, so you can preview from the dashboard and apply on the host. This behavior is intentional and regression-guarded by @@ -135,37 +140,38 @@ one surface without the others fails the suite instead of drifting silently. --- -## 1. CLI Code's Catalog (25 tools) +## 1. CLI Code's Catalog (26 tools) All tools that appear in `/dashboard/cli-code`. Those with `baseUrlSupport: none` are wired through MITM or a manual guide instead of a custom base URL: -| id | name | vendor | baseUrlSupport | configType | acpSpawnable | -| ------------ | -------------------- | ------------------- | -------------- | -------------- | ------------ | -| claude | Claude Code | Anthropic | full | env | true | -| codex | OpenAI Codex CLI | OpenAI | full | custom | true | -| cline | Cline | OSS (ex-Claude Dev) | full | custom | true | -| kilo | Kilo Code | Kilo-Org | full | custom | false | -| roo | Roo Code | Roo (OSS) | full | guide | false | -| continue | Continue | continue.dev | full | guide | false | -| aider | Aider | OSS (P. Gauthier) | full | guide | true | -| forge | ForgeCode | Antinomy HQ | full | custom | true | -| jcode | jcode | 1jehuang (OSS) | full | custom | false | -| deepseek-tui | DeepSeek TUI | Hunter Bown (OSS) | full | custom | false | -| codewhale | CodeWhale | Hmbown (OSS) | full | custom | false | -| opencode | OpenCode | Anomaly (ex-SST) | full | guide | true | -| droid | Factory Droid | Factory AI | partial | guide | false | -| copilot | GitHub Copilot CLI | GitHub/MS | full | custom | false | -| cursor-cli | Cursor CLI | Anysphere | partial | guide | true | -| smelt | Smelt | leonardcser (OSS) | full | custom | false | -| pi | Pi (pi-coding-agent) | M. Zechner (OSS) | full | custom | false | -| grok-build | Grok Build | xAI | full | custom | false | -| crush | Crush | OSS (Charm) | full | custom | false | -| qwen | Qwen Code | Alibaba | full | guide | true | -| cursor | Cursor | Anysphere | none | guide | false | -| antigravity | Antigravity | Google | none | mitm | false | -| hermes | Hermes | Nous Research | none | guide | false | -| kiro | Kiro AI | Amazon | none | mitm | false | -| custom | Custom CLI | — | full | custom-builder | false | +| id | name | vendor | baseUrlSupport | configType | acpSpawnable | +| ------------ | ----------------------- | ------------------- | -------------- | -------------- | ------------ | +| claude | Claude Code | Anthropic | full | env | true | +| codex | OpenAI Codex CLI | OpenAI | full | custom | true | +| zcode | ZCode (GLM Coding Plan) | Z.ai | none | custom | false | +| cline | Cline | OSS (ex-Claude Dev) | full | custom | true | +| kilo | Kilo Code | Kilo-Org | full | custom | false | +| roo | Roo Code | Roo (OSS) | full | guide | false | +| continue | Continue | continue.dev | full | guide | false | +| aider | Aider | OSS (P. Gauthier) | full | guide | true | +| forge | ForgeCode | Antinomy HQ | full | custom | true | +| jcode | jcode | 1jehuang (OSS) | full | custom | false | +| deepseek-tui | DeepSeek TUI | Hunter Bown (OSS) | full | custom | false | +| codewhale | CodeWhale | Hmbown (OSS) | full | custom | false | +| opencode | OpenCode | Anomaly (ex-SST) | full | guide | true | +| droid | Factory Droid | Factory AI | partial | guide | false | +| copilot | GitHub Copilot CLI | GitHub/MS | full | custom | false | +| cursor-cli | Cursor CLI | Anysphere | partial | guide | true | +| smelt | Smelt | leonardcser (OSS) | full | custom | false | +| pi | Pi (pi-coding-agent) | M. Zechner (OSS) | full | custom | false | +| grok-build | Grok Build | xAI | full | custom | false | +| crush | Crush | OSS (Charm) | full | custom | false | +| qwen | Qwen Code | Alibaba | full | guide | true | +| cursor | Cursor | Anysphere | none | guide | false | +| antigravity | Antigravity | Google | none | mitm | false | +| hermes | Hermes | Nous Research | none | guide | false | +| kiro | Kiro AI | Amazon | none | mitm | false | +| custom | Custom CLI | — | full | custom-builder | false | Tools with `baseUrlSupport: "partial"` show a badge "⚠ Base URL parcial" in the dashboard card. --- @@ -385,7 +391,8 @@ export OPENAI_BASE_URL="http://localhost:20128/v1" export OPENAI_API_KEY="sk-your-omniroute-key" export ANTHROPIC_BASE_URL="http://localhost:20128" export ANTHROPIC_AUTH_TOKEN="sk-your-omniroute-key" -export GEMINI_BASE_URL="http://localhost:20128/v1" +# Gemini CLI reads GOOGLE_GEMINI_BASE_URL at the ROOT (its SDK appends /v1beta/... itself) +export GOOGLE_GEMINI_BASE_URL="http://localhost:20128" export GEMINI_API_KEY="sk-your-omniroute-key" ``` diff --git a/docs/reference/ENVIRONMENT.md b/docs/reference/ENVIRONMENT.md index e54c54dca5..0c206f4ada 100644 --- a/docs/reference/ENVIRONMENT.md +++ b/docs/reference/ENVIRONMENT.md @@ -87,7 +87,7 @@ OmniRoute uses **SQLite** (via `better-sqlite3`) for all persistence. These vari | `OMNIROUTE_BUILD_SHA` | _(unset)_ | `src/lib/monitoring/buildSha.ts` | Git SHA of the running artifact. Stamped by `npm run build:release`; injectable in containers that ship without the `dist/BUILD_SHA` sentinel. Surfaced as `system.buildSha` on `/api/monitoring/health`. | | `OMNIROUTE_RELEASE_REF` | `origin/main` | `scripts/build/buildProvenance.ts` | Ref the pack-artifact provenance gate checks the build SHA against (#10427). | | `OMNIROUTE_ALLOW_CANARY_BUILD` | _(unset)_ | `scripts/build/buildProvenance.ts` | Set to `1` to allow packing a build whose SHA is not on the release line, recording it as a deliberate canary instead of failing the gate (#10427). | -| `OMNIROUTE_SMOKE_API_KEY` | _(unset)_ | `scripts/ops/deploy-canary.mjs` | API key for the canary-deploy smoke probe, sent as `Authorization: Bearer` on `/v1/chat/completions`. Only used by the deploy script (#10429), never by the server. | +| `OMNIROUTE_SMOKE_API_KEY` | _(unset)_ | `scripts/ops/deploy-canary.mjs` | API key for the canary-deploy smoke probe, sent as `Authorization: Bearer` on `/v1/chat/completions`. Only used by the deploy script (#10429), never by the server. Not related to the `OMNIROUTE_SMOKE_*` variables of the opt-in CLI smoke harness (`RUN_CLI_SMOKE=1`, `OMNIROUTE_SMOKE_BASE_URL/MODEL/API_KEY_ENV/TARGETS/TIMEOUT_MS` in `tests/integration/upstream-cli-smoke.int.test.ts`) — see [CLI Integrations → Real smoke sweep](../guides/CLI-INTEGRATIONS.md). | | `OMNIROUTE_DATA_DIR` | _(unset)_ | `open-sse/executors/promptql/threadSticky.ts` | **Fallback alias** for `DATA_DIR`, checked only when `DATA_DIR` is unset. Used to locate the PromptQL executor's on-disk thread-sticky session cache (`/promptql-thread-sessions.json`); if neither var is set, the cache stays in-memory only (not persisted across restarts). | | `STORAGE_ENCRYPTION_KEY` | _(empty = disabled)_ | `src/lib/db/encryption.ts` | AES key for full SQLite database encryption at rest. Generate with `openssl rand -hex 32`. | | `STORAGE_ENCRYPTION_KEY_VERSION` | `v1` | `scripts/build/bootstrap-env.mjs`, `electron/main.js` | Version label for the encryption key. Increment when performing key rotation to support decryption of old backups. | @@ -380,7 +380,7 @@ Controls how OmniRoute discovers and launches CLI sidecars (Claude Code, Codex, | `CLI_MODE` | `auto` | `src/shared/services/cliRuntime.ts` | `auto` = search system PATH; `manual` = use explicit paths only. | | `CLI_EXTRA_PATHS` | _(unset)_ | `src/shared/services/cliRuntime.ts` | Additional PATH entries for CLI binary discovery (colon-separated). | | `CLI_CONFIG_HOME` | _(unset)_ | `src/shared/services/cliRuntime.ts` | Override home directory for reading CLI configs (`~/.claude`, `~/.codex`). Must be absolute and inside the process home — **or**, in a container, a bind-mounted path (that is how `/host-home` works). Anything else falls back to the home dir. | -| `CLI_ALLOW_CONFIG_WRITES` | `false` | `src/shared/services/cliRuntime.ts` | Allow OmniRoute to write CLI config files (token refresh, session data). | +| `CLI_ALLOW_CONFIG_WRITES` | `true` | `src/shared/services/cliRuntime.ts` | Allow OmniRoute to write CLI config files (token refresh, session data). Set to `false` to make every CLI config write fail with an explicit "writes disabled" error. | | `CLI_CLAUDE_BIN` | `claude` | `src/shared/services/cliRuntime.ts` | Custom path to Claude CLI binary. | | `CLI_CODEX_BIN` | `codex` | `src/shared/services/cliRuntime.ts` | Custom path to Codex CLI binary. | | `CLI_DROID_BIN` | `droid` | `src/shared/services/cliRuntime.ts` | Custom path to Droid CLI binary. | @@ -388,11 +388,11 @@ Controls how OmniRoute discovers and launches CLI sidecars (Claude Code, Codex, | `CLI_CURSOR_BIN` | `agent` | `src/shared/services/cliRuntime.ts` | Custom path to Cursor agent binary. | | `CLI_CLINE_BIN` | `cline` | `src/shared/services/cliRuntime.ts` | Custom path to Cline CLI binary. | | `CLI_CONTINUE_BIN` | `cn` | `src/shared/services/cliRuntime.ts` | Custom path to Continue CLI binary. | -| `CLI_QODER_BIN` | `qoder` | `src/shared/services/cliRuntime.ts` | Custom path to Qoder CLI binary. | +| `CLI_QODER_BIN` | `qodercli` | `src/shared/services/cliRuntime.ts` | Custom path to Qoder CLI binary. | | `CLI_QWEN_BIN` | `qwen` | `src/shared/services/cliRuntime.ts` | Custom path to the Qwen Code CLI binary. | | `CLI_AIDER_BIN` | `aider` | `src/shared/services/cliRuntime.ts` | Custom path to the Aider CLI binary. | | `CLI_GOOSE_BIN` | `goose` | `src/shared/services/cliRuntime.ts` | Custom path to the Goose CLI binary. | -| `CLI_GEMINI_BIN` | `gemini` | `src/shared/services/cliRuntime.ts` | Custom path to the Google Gemini CLI binary (used by detection and `omniroute run gemini`). | +| `CLI_GEMINI_BIN` | `gemini` | `src/shared/services/cliRuntime.ts` | Custom path to the Google Gemini CLI binary — server-side detection/health checks only; `omniroute run gemini` resolves the `gemini` binary from `PATH`. | | `CLI_DEVIN_BIN` | `devin` | `open-sse/executors/devin-cli.ts` | Custom path to the Devin CLI binary (v3.8.0). Used by the Windsurf/Devin executor. | | `DEVIN_DESKTOP_VERSION` | `3.6.27` | `open-sse/executors/devin-desktop.ts` | Devin Desktop `ide_version`. Overrides must use `x.y.z` format; invalid values fall back to the verified default. | | `DEVIN_DESKTOP_EXTENSION_VERSION` | `1.48.2` | `open-sse/executors/devin-desktop.ts` | Bundled Codeium/language-server `extension_version`, distinct from Desktop `ide_version`. Overrides must use `x.y.z`; invalid values use the bundled default. |