| # OmniRoute CLI — Internal Conventions | |
| > Status: normative. Source: `_tasks/features-v3.8.0/cli/fase-0-preparacao/0.3-definir-convencoes.md`. | |
| > This file is the authoritative reference for every new or migrated CLI command. | |
| > If reality diverges from this document, fix the code first; only edit this file | |
| > after the discrepancy has been justified in a PR. | |
| ## 1. Subcommand style | |
| **Standard**: `git`-style nested verbs. | |
| ``` | |
| omniroute keys add openai sk-xxx | |
| omniroute combo switch fastest | |
| omniroute memory search "react hooks" | |
| ``` | |
| **Not allowed**: | |
| ``` | |
| omniroute --add-key openai sk-xxx # ❌ flag-as-verb | |
| omniroute add-key openai sk-xxx # ❌ hyphen at the top level | |
| ``` | |
| ## 2. Flags | |
| - Only `--long` and `-s` shorts (one-letter shorts reserved for very common | |
| flags: `-h`, `-v`, `-o`, `-q`, `--no-open`). | |
| - Format: `--api-key sk-xxx` (space). `=` accepted for parity but doc uses space. | |
| - Naming: kebab-case (`--api-key`, `--non-interactive`, `--max-tokens`). | |
| - Booleans: `--no-foo` (negative) and `--foo` (positive). Default `false` unless | |
| documented. | |
| - Multi-value: repeat the flag (`--header X-A=1 --header X-B=2`). | |
| ## 3. Output (`--output`) | |
| | Value | Use case | | |
| | ------- | -------------------------------------------- | | |
| | `table` | default human-readable | | |
| | `json` | single JSON object, pretty-printed | | |
| | `jsonl` | streamed objects, one per line (logs, lists) | | |
| | `csv` | spreadsheet ingestion | | |
| Related flags: | |
| - `--quiet` / `-q` — suppress headers/spinners (pipe-friendly). | |
| - `--no-color` — force ANSI off (auto-detected if `!stdout.isTTY`). | |
| Helper: `emit(rows, opts)` from `bin/cli/output.mjs` handles all four formats. | |
| ## 4. Exit codes | |
| | Code | Meaning | | |
| | ----- | --------------------------------- | | |
| | `0` | success | | |
| | `1` | generic error (uncaught, runtime) | | |
| | `2` | invalid argument / misuse | | |
| | `3` | server offline (when required) | | |
| | `4` | auth / permission (401/403) | | |
| | `5` | rate limit / quota (429) | | |
| | `124` | timeout | | |
| Helper: `exitWith(code, message?)` from `bin/cli/exit.mjs` (added under | |
| `output.mjs` if needed) — always uses these constants. **Never** raw | |
| `process.exit(N)` in command code. | |
| ## 5. HTTP errors + retry/backoff | |
| All API calls go through `apiFetch(path, opts)` (`bin/cli/api.mjs`), which: | |
| - Reads base URL from `OMNIROUTE_BASE_URL` env or `~/.omniroute/config.json` | |
| (active profile). | |
| - Injects `Authorization: Bearer ${OMNIROUTE_API_KEY}` when available. | |
| - Injects `x-omniroute-cli-token` when applicable (see task 8.12). | |
| - Applies a per-attempt timeout (`--timeout 30000`, default 30s). | |
| - Maps status → exit code (401→4, 429→5, 5xx→1, etc.). | |
| - Never exposes `err.stack` (CLAUDE.md hard rule #12). | |
| - Applies exponential backoff with jitter on retryable statuses. | |
| ### Retry defaults | |
| ```js | |
| export const RETRY_DEFAULTS = { | |
| maxAttempts: 3, // 1 initial + 2 retries | |
| baseMs: 500, | |
| maxMs: 8000, // jitter can slightly exceed | |
| jitter: true, // ±25% | |
| retryableStatuses: [408, 425, 429, 502, 503, 504], | |
| retryableErrorCodes: [ | |
| "ECONNRESET", | |
| "ECONNREFUSED", | |
| "ETIMEDOUT", | |
| "ENOTFOUND", | |
| "EAI_AGAIN", | |
| "EPIPE", | |
| ], | |
| }; | |
| ``` | |
| ### Global flags wired | |
| - `--retry` (default on) / `--no-retry` | |
| - `--retry-max <n>` (default 3) — total attempts | |
| - `--timeout <ms>` (default 30000) — per attempt | |
| - `--retry-on <csv>` — extra retryable statuses (e.g. `--retry-on 500`) | |
| ### Method semantics | |
| - Mutations (`POST`/`PUT`/`DELETE`) retry **only** on idempotent-ish statuses | |
| (`502`/`503`/`504`/`408`/network), never `409`/`422`. This avoids duplicate | |
| side-effects. | |
| - `GET` retries all `RETRY_DEFAULTS.retryableStatuses`. | |
| - SSE / streaming does **not** auto-retry (operator decides). | |
| - Optional `--idempotency-key <uuid>` for extra-safe mutations. | |
| ### Status → exit code map | |
| | Status | Exit | Retry? | | |
| | --------------- | ---- | ------------------------------ | | |
| | 200–299 | 0 | n/a | | |
| | 400 | 2 | no | | |
| | 401 | 4 | no | | |
| | 403 | 4 | no | | |
| | 404 | 2 | no | | |
| | 408 | 124 | **yes** | | |
| | 409 | 1 | no (mutations) | | |
| | 422 | 2 | no | | |
| | 425 | 1 | **yes** | | |
| | 429 | 5 | **yes** (respects Retry-After) | | |
| | 500 | 1 | configurable (default no) | | |
| | 502 / 503 / 504 | 1 | **yes** | | |
| | Network errors | 1 | **yes** | | |
| | Timeout | 124 | **yes** | | |
| ## 6. Internationalization | |
| - Every user-facing string goes through `t("module.key", vars)`. | |
| - Catalogs live in `bin/cli/locales/{locale}.json` (nested objects). | |
| 42 files ship out-of-the-box: `en`, `pt-BR`, and 40 additional locales. | |
| 11 locales are scaffold-only (empty `{}`); all keys fall back to `en` automatically. | |
| - Detection order: `--lang` flag → `OMNIROUTE_LANG` env → `LC_ALL` → `LC_MESSAGES` → `LANG` → `en`. | |
| - Locale persisted via `config lang set <code>` — saves `OMNIROUTE_LANG` to `~/.omniroute/.env`. | |
| - Missing keys return the key itself (no crash). | |
| - PRs that add new strings **must** update `en.json` and `pt-BR.json`. | |
| Other locale files are best-effort; missing keys silently fall back to `en`. | |
| - `normalize()` in `i18n.mjs` validates locale codes via `/^[a-zA-Z0-9-]+$/` to | |
| prevent path traversal — never pass raw filesystem paths. | |
| - Canonical locale list: `config/i18n.json` — source of truth used by both CLI and | |
| dashboard i18n pipelines. | |
| ### Adding a new locale file | |
| 1. Add entry to `config/i18n.json` with `code`, `english`, `native`, `flag`. | |
| 2. Run `node bin/cli/scripts/generate-locales.mjs` — creates `bin/cli/locales/{code}.json`. | |
| 3. Fill in translations (or leave as `{}` for en-fallback scaffold). | |
| 4. The pre-commit hook `check-cli-i18n` will verify all `t()` keys exist in `en.json`. | |
| ## 7. Logs / output channels | |
| - `stdout` — useful output (parseable when `--output json|jsonl|csv`). | |
| - `stderr` — progress, warnings, errors, spinners. | |
| - `--verbose` / `-V` — extra detail on stderr. | |
| - `--debug` — stack traces, request bodies (dev-mode only; redacts secrets). | |
| ## 8. Server-first / DB-fallback | |
| Single helper: | |
| ```js | |
| import { withRuntime } from "./runtime.mjs"; | |
| await withRuntime(async ({ kind, api, db }) => { | |
| if (kind === "http") | |
| return api("/api/combos", { retry: false, timeout: 5000, acceptNotOk: true }); | |
| return db.combos.getCombos(); | |
| }); | |
| ``` | |
| - `kind: "http"` when server is up (preferred). `api` is `apiFetch` bound to | |
| the current profile/base-URL. | |
| - `kind: "db"` when server is offline. `db` exposes typed module exports: | |
| - `db.combos` → `src/lib/db/combos.ts` (getCombos, getComboByName, createCombo, | |
| deleteComboByName, setActiveCombo, …) | |
| - `db.recovery` → `src/lib/db/recovery.ts` (countEncryptedCredentials, | |
| resetEncryptedColumns) | |
| - Mutations that require server **must** error with exit code `3` when the | |
| server is down, never silently fall back. | |
| - **Never** write raw SQL in commands — always go through `src/lib/db/` modules. | |
| The Semgrep rule at `.semgrep/rules/cli-no-sqlite.yaml` enforces this at commit time. | |
| ## 9. Audit of destructive actions | |
| Commands that mutate state (delete, reset, `--force`) **must**: | |
| - Ask for interactive confirmation (skipped with `--yes`). | |
| - POST to `/api/compliance/audit-log` when the server is up. | |
| - Support `--dry-run` (preview without effect). | |
| ## 10. Secrets | |
| - **Never** log secrets. Mask as `sk-***-xxx` via `maskSecret()` from | |
| `bin/cli/output.mjs`. | |
| - **Never** accept a secret via positional without warning. Prefer: | |
| - env (`OMNIROUTE_*_API_KEY`) | |
| - stdin (`--api-key-stdin`) | |
| - interactive `askSecret()` (echo off — already implemented in `io.mjs`) | |
| - Secrets must not appear in `--verbose` / `--debug` output. | |
| ## 11. Testing baseline | |
| - Every new command ships with at least one smoke test (happy path + one | |
| error path). | |
| - Use `tests/unit/cli-*.test.ts` naming. Prefer `node:test` for CLI suites | |
| (no extra deps). | |
| - Coverage target: ≥60% for `bin/cli/commands/`, ≥75% for `bin/cli/` overall | |
| after Fase 8. | |
| ## 12. References | |
| - CLAUDE.md hard rules — especially #11 (publicCreds), #12 (error | |
| sanitization), #13 (shell injection). | |
| - `docs/security/ERROR_SANITIZATION.md` — the only acceptable error shapes. | |
| - `tests/unit/cli-tools-i18n.test.ts` — current i18n infrastructure (pre-`t()`). | |
| - Commander.js docs — Options & subcommand patterns. | |