# CLI Tools — OmniRoute (Malti)

🌐 **Languages:** 🇺🇸 [English](../../../../reference/CLI-TOOLS.md) · 🇪🇹 [am](../../../am/docs/reference/CLI-TOOLS.md) · 🇸🇦 [ar](../../../ar/docs/reference/CLI-TOOLS.md) · 🇦🇿 [az](../../../az/docs/reference/CLI-TOOLS.md) · 🇧🇬 [bg](../../../bg/docs/reference/CLI-TOOLS.md) · 🇧🇩 [bn](../../../bn/docs/reference/CLI-TOOLS.md) · 🇧🇦 [bs](../../../bs/docs/reference/CLI-TOOLS.md) · 🇨🇿 [cs](../../../cs/docs/reference/CLI-TOOLS.md) · 🇩🇰 [da](../../../da/docs/reference/CLI-TOOLS.md) · 🇩🇪 [de](../../../de/docs/reference/CLI-TOOLS.md) · 🇬🇷 [el](../../../el/docs/reference/CLI-TOOLS.md) · 🇪🇸 [es](../../../es/docs/reference/CLI-TOOLS.md) · 🇪🇪 [et](../../../et/docs/reference/CLI-TOOLS.md) · 🇮🇷 [fa](../../../fa/docs/reference/CLI-TOOLS.md) · 🇫🇮 [fi](../../../fi/docs/reference/CLI-TOOLS.md) · 🇫🇷 [fr](../../../fr/docs/reference/CLI-TOOLS.md) · 🇮🇪 [ga](../../../ga/docs/reference/CLI-TOOLS.md) · 🇮🇳 [gu](../../../gu/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ha](../../../ha/docs/reference/CLI-TOOLS.md) · 🇮🇱 [he](../../../he/docs/reference/CLI-TOOLS.md) · 🇮🇳 [hi](../../../hi/docs/reference/CLI-TOOLS.md) · 🇭🇷 [hr](../../../hr/docs/reference/CLI-TOOLS.md) · 🇭🇺 [hu](../../../hu/docs/reference/CLI-TOOLS.md) · 🇦🇲 [hy](../../../hy/docs/reference/CLI-TOOLS.md) · 🇮🇩 [id](../../../id/docs/reference/CLI-TOOLS.md) · 🇳🇬 [ig](../../../ig/docs/reference/CLI-TOOLS.md) · 🇮🇹 [it](../../../it/docs/reference/CLI-TOOLS.md) · 🇯🇵 [ja](../../../ja/docs/reference/CLI-TOOLS.md) · 🇬🇪 [ka](../../../ka/docs/reference/CLI-TOOLS.md) · 🇰🇭 [km](../../../km/docs/reference/CLI-TOOLS.md) · 🇮🇳 [kn](../../../kn/docs/reference/CLI-TOOLS.md) · 🇰🇷 [ko](../../../ko/docs/reference/CLI-TOOLS.md) · 🇱🇹 [lt](../../../lt/docs/reference/CLI-TOOLS.md) · 🇱🇻 [lv](../../../lv/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ml](../../../ml/docs/reference/CLI-TOOLS.md) · 🇮🇳 [mr](../../../mr/docs/reference/CLI-TOOLS.md) · 🇲🇾 [ms](../../../ms/docs/reference/CLI-TOOLS.md) · 🇲🇲 [my](../../../my/docs/reference/CLI-TOOLS.md) · 🇳🇵 [ne](../../../ne/docs/reference/CLI-TOOLS.md) · 🇳🇱 [nl](../../../nl/docs/reference/CLI-TOOLS.md) · 🇳🇴 [no](../../../no/docs/reference/CLI-TOOLS.md) · 🇮🇳 [or](../../../or/docs/reference/CLI-TOOLS.md) · 🇮🇳 [pa](../../../pa/docs/reference/CLI-TOOLS.md) · 🇵🇭 [phi](../../../phi/docs/reference/CLI-TOOLS.md) · 🇵🇱 [pl](../../../pl/docs/reference/CLI-TOOLS.md) · 🇵🇹 [pt](../../../pt/docs/reference/CLI-TOOLS.md) · 🇧🇷 [pt-BR](../../../pt-BR/docs/reference/CLI-TOOLS.md) · 🇷🇴 [ro](../../../ro/docs/reference/CLI-TOOLS.md) · 🇷🇺 [ru](../../../ru/docs/reference/CLI-TOOLS.md) · 🇱🇰 [si](../../../si/docs/reference/CLI-TOOLS.md) · 🇸🇰 [sk](../../../sk/docs/reference/CLI-TOOLS.md) · 🇸🇮 [sl](../../../sl/docs/reference/CLI-TOOLS.md) · 🇷🇸 [sr](../../../sr/docs/reference/CLI-TOOLS.md) · 🇸🇪 [sv](../../../sv/docs/reference/CLI-TOOLS.md) · 🇰🇪 [sw](../../../sw/docs/reference/CLI-TOOLS.md) · 🇮🇳 [ta](../../../ta/docs/reference/CLI-TOOLS.md) · 🇮🇳 [te](../../../te/docs/reference/CLI-TOOLS.md) · 🇹🇭 [th](../../../th/docs/reference/CLI-TOOLS.md) · 🇹🇷 [tr](../../../tr/docs/reference/CLI-TOOLS.md) · 🇺🇦 [uk-UA](../../../uk-UA/docs/reference/CLI-TOOLS.md) · 🇵🇰 [ur](../../../ur/docs/reference/CLI-TOOLS.md) · 🇺🇿 [uz](../../../uz/docs/reference/CLI-TOOLS.md) · 🇻🇳 [vi](../../../vi/docs/reference/CLI-TOOLS.md) · 🇳🇬 [yo](../../../yo/docs/reference/CLI-TOOLS.md) · 🇨🇳 [zh-CN](../../../zh-CN/docs/reference/CLI-TOOLS.md) · 🇹🇼 [zh-TW](../../../zh-TW/docs/reference/CLI-TOOLS.md)

---

Aġġornat l-aħħar: 2026-08-23

OmniRoute jintegra ma’ tliet kategoriji ta’ għodod CLI mifruxa fuq tliet paġni ddedikati tad-dashboard:

| Paġna          | Rotta                   | Kunċett                                                                                   | Għadd          |
| -------------- | ----------------------- | ----------------------------------------------------------------------------------------- | -------------- |
| **Kodiċi CLI** | `/dashboard/cli-code`   | Għodod tal-ipprogrammar li tipponta lejn OmniRoute (Klijent → CLI → OmniRoute → Fornitur) | 26             |
| **Aġenti CLI** | `/dashboard/cli-agents` | Aġenti awtonomi li tipponta lejn OmniRoute (l-istess fluss, ambitu usa’)                  | 10             |
| **Aġenti ACP** | `/dashboard/acp-agents` | CLIs li OmniRoute iniedi bħala backend permezz ta’ stdio/ACP (fluss bil-maqlub)           | ara r-reġistru |

Ir-rotot preċedenti jagħmlu redirect permezz ta’ 308: `/dashboard/cli-tools` → `/dashboard/cli-code`, `/dashboard/agents` → `/dashboard/acp-agents`.

---

## Kif Jaħdem

```
Kodiċi CLI / Aġenti CLI (fluss tal-konsum):
Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ...
           │
           ▼  (kollha jippontaw lejn OmniRoute)
    http://YOUR_SERVER:20128/v1
           │
           ▼  (OmniRoute jidderieġi lejn il-fornitur it-tajjeb)
    Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...

Aġenti ACP (fluss ta’ tnedija bil-maqlub):
    Talba tal-klijent → OmniRoute → iniedi CLI permezz ta’ stdio/ACP → tweġiba
```

**Benefiċċji:**

- Ċavetta API waħda biex timmaniġġja l-għodod kollha
- Traċċar tal-ispejjeż tal-CLIs kollha fid-dashboard
- Qlib bejn mudelli mingħajr ma terġa’ tikkonfigura kull għodda
- Jaħdem lokalment u fuq servers remoti (VPS, Docker, Akamai, Cloudflare Tunnel)

---

## Ikkonfigura awtomatikament b’`setup-*`

M’għandekx għalfejn tikteb il-konfigurazzjoni ta’ kull għodda manwalment. OmniRoute jipprovdi kmand `setup-*`
għal kull CLI appoġġjat li jaqra l-katalgu **attiv** tal-mudelli minn istanza ta’
OmniRoute li tkun qed taħdem (lokali jew remota) u jikteb il-konfigurazzjoni tal-għodda stess fuq il-magna tiegħek:

```bash
omniroute setup-codex        omniroute setup-claude       omniroute setup-opencode
omniroute setup-cline        omniroute setup-kilo         omniroute setup-continue
omniroute setup-cursor       omniroute setup-roo          omniroute setup-crush
omniroute setup-goose        omniroute setup-qwen         omniroute setup-aider
omniroute setup-5dive
```

Kull wieħed jaċċetta `--remote <url> --api-key <key>` (ikkonfigura għodda lokali ma’
OmniRoute remot), `--dry-run` (ara previżjoni mingħajr kitba), u `--port`. Għodod
mingħajr skoperta awtomatika tal-mudelli (Cline, Kilo, Roo, Goose, Aider, Qwen, 5dive) jieħdu
`--model <id>` (u `--yes` għal eżekuzzjonijiet mhux interattivi). `setup-5dive` huwa l-unika
riċetta li ma tiktebx taħt `$HOME`: tikkonfigura flotta ta’ aġenti 5dive billi
tikteb profil tal-awtentikazzjoni li huwa proprjetà ta’ root fuq il-host tal-flotta, għalhekk terġa’ teżegwixxi lilha nfisha permezz ta’ `sudo`
u m’għandhiex modalità remota tagħha stess. Biex tniedi CLI bl-ambjent
it-tajjeb injettat u mingħajr ma tinkiteb ebda konfigurazzjoni, uża l-lanċjatur ġeneriku
`omniroute run <target>` (claude, codex, aider, goose, opencode, qwen,
gemini — it-targets u l-aliases jiġu minn `bin/cli/cli-manifest.mjs`); il-lanċjaturi preċedenti
għal kull għodda `omniroute launch` (Claude Code) u `omniroute launch-codex`
(Codex) għadhom disponibbli. Gemini CLI jista’ jitnieda biss: huwa target ta’ `omniroute run`
iżda m’għandux riċetta `setup-*`/`configure`.

> **Referenza sħiħa:** it-tabella ewlenija — x’jikteb kull kmand, kull flag,
> lokali kontra remot, u liema għodod jeħtieġu s-suffiss `/v1` — tinsab f’
> **[Integrazzjonijiet CLI](../guides/CLI-INTEGRATIONS.md)**.

### Eżekuzzjoni ta’ dawn ġewwa container

Kmand `setup-*` eżegwit ġewwa l-container ta’ OmniRoute jikteb fil-home
tal-container stess, li ma jinqara minn ebda CLI tal-host u li jisparixxi mal-
container. OmniRoute jidentifika dan u joħroġ b’`2` flimkien ma’ struzzjonijiet minflok
ma jikteb. Hemm żewġ modi appoġġjati biex tkompli — installa s-CLI fuq il-host u
uża `omniroute connect` biex tikkonnettja mal-container, jew immonta b’bind id-direttorji tal-konfigurazzjoni u ssettja
`CLI_CONFIG_HOME` (il-profil `host` ta’ compose). Kull kmand `setup-*`, kif ukoll
`omniroute configure` u `omniroute config set`, jaċċetta
`--allow-container-write` meta dak li tassew trid tagħmel huwa li tikkonfigura l-CLIs tal-container
stess; `OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true` jagħmel l-istess għas-
server. Ara
[Gwida Docker → Konfigurazzjoni tal-għodod CLI tal-host](../guides/DOCKER_GUIDE.md#configuring-host-cli-tools-when-omniroute-runs-in-docker).

Il-**punt ta’ tmiem għall-applikazzjoni** tad-dashboard (`POST /api/cli-tools/apply`) jinforza l-
istess protezzjoni: f’container, kitba li t-target tagħha mhuwiex immuntat b’bind mill-
host twieġeb b’**`422`** b’`containerEphemeralTarget: true`, it-test sigur tal-iżball
u — għall-għodod li għandhom riċetta għall-host (claude, codex, opencode, cline,
kilo, continue) — `hostSetupCommand` (eż. `omniroute setup-opencode`) biex jiġi eżegwit
fuq il-host minflok; ma jinkiteb xejn. `dryRun: true` jibqa’ jaħdem fil-modalità
container u jirritorna previżjoni b’informazzjoni sensittiva moħbija + il-passaġġ tat-target mingħajr ma jmiss id-diska. Il-kontenut
tal-previżjoni mhuwiex konfigurazzjoni li tinkludi kredenzjali biex tiġi kkupjata jew importata. Applika
bl-inputs oriġinali tal-għodda/URL bażi/ċavetta API/mudell fuq il-host, jew uża l-kmand indikat
ta’ setup min-naħa tal-host. Ara [Sigurtà tal-konfigurazzjoni CLI](../security/CLI-CONFIGURATION.md)
għall-header tal-previżjoni u l-kuntratt tat-talba. Din l-imġiba hija
intenzjonata u protetta kontra rigressjonijiet minn
`tests/unit/api/cli-tools/apply-container-guard.test.ts` — qatt “tirranġa” 422
billi tneħħi l-protezzjoni.

---

## Sors Awtorevoli

Il-katalgu unifikat jinsab f’`src/shared/constants/cliTools.ts` bħala `CLI_TOOLS: Record<string, CliCatalogEntry>`.

Kull entrata għandha dawn l-oqsma (iddefiniti f’`src/shared/schemas/cliCatalog.ts`):

| Qasam                                           | Tip                                                          | Deskrizzjoni                                                                       |
| ----------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| `category`                                      | `"code" \| "agent"`                                          | Fuq liema paġna tidher l-għodda                                                    |
| `vendor`                                        | `string`                                                     | L-oriġini tal-għodda ("Anthropic", "OSS (P. Gauthier)")                            |
| `acpSpawnable`                                  | `boolean`                                                    | Tista’ tintuża wkoll bħala Aġent ACP (tintwera badge)                              |
| `baseUrlSupport`                                | `"full" \| "partial" \| "none"`                              | Livell ta’ appoġġ għal endpoint personalizzat. `"none"` = xogħol pendenti tal-MITM |
| `configType`                                    | `"env" \| "custom" \| "guide" \| "custom-builder" \| "mitm"` | Mekkaniżmu ta’ konfigurazzjoni                                                     |
| `id`, `name`, `color`, `description`, `docsUrl` | standard                                                     | Oqsma ewlenin tal-wiri                                                             |

L-entrati b’`baseUrlSupport: "none"` **ma jintwerewx** fil-paġni tad-dashboard — huma rreġistrati fix-xogħol pendenti tal-MITM għall-pjan 11 (ara `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md`).

### Livelli ta’ kapaċità (ikkatalogata × individwabbli × konfigurabbli × eżegwibbli)

Mhux kull għodda kkatalogata tista’ tiġi individwata, ikkonfigurata jew eżegwita. Kull livell għandu sors wieħed
li jiddikjarah, u test tad-diskrepanzi jżommhom allinjati:

| Livell            | Tifsira                                                                                          | Iddikjarat fi                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------- |
| **Ikkatalogata**  | Tidher fil-katalgu tad-dashboard (isem, fornitur, dokumentazzjoni, tip ta’ konfigurazzjoni)      | `src/shared/constants/cliTools.ts` (`CLI_TOOLS`)                      |
| **Individwabbli** | Individwazzjoni tal-binarju/konfigurazzjoni, kontrolli tas-saħħa, mogħdijiet tal-konfigurazzjoni | `src/shared/services/cliRuntime.ts` (katalgu tar-runtime `CLI_TOOLS`) |
| **Konfigurabbli** | Appoġġjata minn `omniroute configure <cli>` (teżisti riċetta tal-konfigurazzjoni)                | `bin/cli/cli-manifest.mjs` (`configure: true`)                        |
| **Eżegwibbli**    | Appoġġjata minn `omniroute run <target>` (injezzjoni tal-env/argumenti ddefinita)                | `bin/cli/cli-manifest.mjs` (`run: true`)                              |

`bin/cli/cli-manifest.mjs` huwa l-manifest eżegwibbli kanoniku għall-uċuħ tal-kmandi
tas-CLI: `run`, `configure` u l-ġeneraturi tal-awtokompletament tas-shell kollha jisiltu minnu
l-listi tal-miri tagħhom, ir-riżoluzzjoni tal-aliases (pereżempju `kilocode`/`kilo-code`/`kilo_cli` → `kilo`)
u l-konnessjoni tal-flag `--model`. Il-kontroll kontra d-diskrepanzi
`tests/unit/cli/cli-manifest-drift.test.ts` jivverifika li l-manifest, il-katalgu tar-runtime,
il-katalgu tal-UI u kull wiċċ tal-konsumatur jibqgħu sinkronizzati — mira miżjuda ma’
wiċċ wieħed mingħajr l-oħrajn twassal biex is-sett tat-testijiet ifalli minflok ma jinħolqu diskrepanzi fis-skiet.

---

## 1. Il-Katalgu ta' CLI Code (26 għodda)

L-għodod kollha li jidhru f’`/dashboard/cli-code`. Dawk b’`baseUrlSupport: none` huma kkonfigurati permezz ta’ MITM jew gwida manwali minflok URL bażi personalizzat:

| 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        |

L-għodod b’`baseUrlSupport: "partial"` juru badge "⚠ URL Bażi parzjali" fil-kard tad-dashboard.
---

## 2. Katalgu tal-Aġenti CLI (10 għodod)

Aġenti awtonomi li jidhru f’`/dashboard/cli-agents`:

| id           | name             | vendor                   | baseUrlSupport | acpSpawnable |
| ------------ | ---------------- | ------------------------ | -------------- | ------------ |
| hermes-agent | Hermes Agent     | Nous Research            | full           | false        |
| openclaw     | OpenClaw         | OSS (P. Steinberger)     | full           | true         |
| goose        | Goose            | Block / Linux Foundation | full           | true         |
| interpreter  | Open Interpreter | OSS                      | full           | true         |
| warp         | Warp AI          | Warp Inc.                | partial        | true         |
| agent-deck   | Agent Deck       | asheshgoplani (OSS)      | full           | false        |
| omp          | Oh My Pi         | OSS                      | full           | true         |
| letta        | Letta CLI        | Letta                    | full           | false        |
| prime-agent  | Prime Agent      | Prime Intellect (OSS)    | full           | false        |
| 5dive        | 5dive            | OSS (5dive-ai)           | full           | false        |

---

## 3. Aġenti ACP (/dashboard/acp-agents)

Din il-paġna (li isimha nbidel minn `/dashboard/agents`) turi CLIs li OmniRoute jista’ **jniedi** bħala magni ta’ eżekuzzjoni backend permezz tal-protokoll stdio/ACP. Il-katalgu jinżamm separatament f’`src/lib/acp/registry.ts` u **mhuwiex** l-istess bħal `CLI_TOOLS`.

---

## 4. Xogħol Pendenti tal-MITM (mhux muri fid-dashboard)

Il-CLIs li ġejjin ma jappoġġjawx URL bażi personalizzat b’mod nattiv u **mhumiex elenkati** fil-paġni CLI Code jew CLI Agents. Huma kandidati għall-interċettazzjoni MITM fil-pjan 11:

| CLI                 | Raġuni                                                            |
| ------------------- | ----------------------------------------------------------------- |
| windsurf            | BYOK limitat għal mudelli Claude magħżula + URL/token korporattiv |
| amp                 | Ekosistema magħluqa (Sourcegraph)                                 |
| amazon-q / kiro-cli | Awtentikazzjoni AWS SSO, l-ebda URL personalizzat                 |
| cowork              | Anthropic Desktop, l-ebda endpoint konfigurabbli                  |

Ara `_tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md` għar-referenza inkroċjata sħiħa.

---

## 5. API għad-Detezzjoni f’Lott

Id-detezzjoni kollha tal-għodod hija aggregata permezz ta’ endpoint wieħed:

**`GET /api/cli-tools/all-statuses`**

- Awtentikazzjoni: `requireCliToolsAuth(request)` (l-istess bħal rotot oħra taħt `/api/cli-tools/`)
- Jirritorna: `Record<toolId, ToolBatchStatus>` (tip: `src/shared/types/cliBatchStatus.ts`)
- Strateġija: `Promise.all` fuq l-għodod kollha, timeout ta’ 5s għal kull għodda
- Cache: LRU fil-memorja indiċjat permezz tal-`mtime` tal-fajl tal-konfigurazzjoni. Il-cache jiġi invalidat meta jinbidel l-mtime. Jiġi rrisettjat meta s-server jerġa’ jibda.

Struttura tar-rispons għal kull għodda:

```ts
interface ToolBatchStatus {
  detection: {
    installed: boolean;
    runnable: boolean;
    version?: string;
    command?: string;
    commandPath?: string;
    reason?: string;
  };
  config: {
    status: "configured" | "not_configured" | "not_installed" | "unknown" | "other";
    endpoint?: string | null;
    lastConfiguredAt?: string | null;
  };
  error?: string; // sanitizzat, mingħajr traċċi tal-munzell
}
```

---

## 6. Handlers tas-Settings għal Għodod Ġodda

Għodod ġodda b’`configType: "custom"` għandhom rotot dedikati tal-API għas-settings:

| Rotta                                       | Għodda                                                                            |
| ------------------------------------------- | --------------------------------------------------------------------------------- |
| `POST /api/cli-tools/forge-settings`        | ForgeCode (.forge.toml)                                                           |
| `POST /api/cli-tools/jcode-settings`        | jcode (flag --base-url)                                                           |
| `POST /api/cli-tools/deepseek-tui-settings` | DeepSeek TUI (OPENAI_BASE_URL, legat)                                             |
| `POST /api/cli-tools/codewhale-settings`    | CodeWhale (OPENAI_BASE_URL, primarju + sinkronizzazzjoni mal-legat `~/.deepseek`) |
| `POST /api/cli-tools/smelt-settings`        | Smelt                                                                             |
| `POST /api/cli-tools/pi-settings`           | Aġent tal-ipprogrammar Pi                                                         |
| `POST /api/cli-tools/grok-build-settings`   | Grok Build (~/.grok/config.toml, `[model.omniroute]`)                             |
| `POST /api/cli-tools/qwen-settings`         | Qwen Code (`~/.qwen/settings.json` + key dedikata f’`.env`)                       |

Ir-rotot kollha jużaw `sanitizeErrorMessage()` għat-tweġibiet tal-iżbalji (Regola Stretta #12).

---

## 7. Arkitettura tal-Paġni tad-Dashboard

### CLI Code (`/dashboard/cli-code`)

- `src/app/(dashboard)/dashboard/cli-code/page.tsx` — komponent tas-server
- `src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx` — grilja tal-klijent
- `src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx` — paġna bid-dettalji tal-għodda
- `src/app/(dashboard)/dashboard/cli-code/components/` — 12-il kard speċjalizzata għall-għodod + `ToolDetailClient.tsx`

### Aġenti CLI (`/dashboard/cli-agents`)

- `src/app/(dashboard)/dashboard/cli-agents/page.tsx` — komponent tas-server
- `src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx` — grilja tal-klijent
- `src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx` — jerġa’ juża `ToolDetailClient`

### Aġenti ACP (`/dashboard/acp-agents`)

- `src/app/(dashboard)/dashboard/acp-agents/page.tsx` — komponent tas-server (imċaqlaq minn `agents/`)

### Komponenti Kondiviżi tal-UI (`src/shared/components/cli/`)

| Fajl                    | Għan                                                                    |
| ----------------------- | ----------------------------------------------------------------------- |
| `CliToolCard.tsx`       | Kard intelliġenti tal-istatus (detezzjoni + konfigurazzjoni + endpoint) |
| `CliConceptCard.tsx`    | Kard ta’ spjegazzjoni tal-kunċett għal kull paġna                       |
| `CliComparisonCard.tsx` | Tqabbil bi tliet kolonni bejn it-tipi ta’ CLI                           |
| `BaseUrlSelect.tsx`     | Menù dropdown tal-endpoint (Lokali/Cloud/Personalizzat)                 |
| `ApiKeySelect.tsx`      | Selettur tal-key tal-API                                                |
| `ManualConfigModal.tsx` | Modal bi snippet tal-konfigurazzjoni li jista’ jiġi kkupjat             |

### Hook Kondiviż (`src/shared/hooks/cli/`)

| Fajl                      | Għan                                                                               |
| ------------------------- | ---------------------------------------------------------------------------------- |
| `useToolBatchStatuses.ts` | Jiġbed `/api/cli-tools/all-statuses`, jimmaniġġja l-istat tat-tagħbija/aġġornament |

---

## 8. i18n

Namespaces ġodda miżjuda fil-pjan 14 F9:

| Namespace   | Għan                                                                                                |
| ----------- | --------------------------------------------------------------------------------------------------- |
| `cliCommon` | Strings kondiviżi (tikketti tal-kards, testi tal-kunċetti/tqabbil, tikketti tal-paġna tad-dettalji) |
| `cliCode`   | Strings tal-paġna ta' CLI Code                                                                      |
| `cliAgents` | Strings tal-paġna ta' CLI Agents                                                                    |
| `acpAgents` | Strings tal-paġna ta' ACP Agents                                                                    |

Huma pprovduti traduzzjonijiet sħaħ għall-PT-BR u l-EN. 39 locale oħra jużaw l-EN awtomatikament bħala riżerva permezz ta' merge fil-livell tan-namespace f'`src/i18n/request.ts`.

---

## 9. Bidu Rapidu

### Pass 1 — Ikseb API Key ta' OmniRoute

1. Iftaħ `/dashboard/api-manager` → **Oħloq API Key**
2. Agħtiha isem (eż. `cli-tools`) u agħżel il-permessi kollha
3. Ikkopja l-key — se jkollok bżonnha għal kull CLI hawn taħt

> Il-key tiegħek tidher hekk: `sk-xxxxxxxxxxxxxxxx-xxxxxxxxx`

---

### Pass 2 — Installa l-Għodod CLI

L-għodod kollha bbażati fuq npm jeħtieġu Node.js 22.22.2+ jew 24.x:

```bash
# Claude Code (Anthropic)
npm install -g @anthropic-ai/claude-code

# OpenAI Codex
npm install -g @openai/codex

# OpenCode
npm install -g opencode-ai

# Cline
npm install -g cline

# KiloCode
npm install -g kilocode

# Qwen Code
npm install -g @qwen-code/qwen-code

# Google Gemini CLI (jista' jitħaddem permezz ta' `omniroute run gemini` → interfaċċa /v1beta)
npm install -g @google/gemini-cli

# Aider
pip install aider-chat

# Smelt
cargo install smelt  # Ibbażat fuq Rust

# Aġent tal-ipprogrammar Pi
# ara https://github.com/zechnerj/pi-coding-agent għall-installazzjoni

# jcode
# ara https://github.com/1jehuang/jcode għall-installazzjoni
```

---

### Pass 3 — Ikkonfigura permezz tad-Dashboard

1. Mur f'`http://localhost:20128/dashboard/cli-code`
2. Sib l-għodda tiegħek fil-grilja
3. Ikklikkja l-kard biex tiftaħ il-paġna tad-dettalji tal-għodda
4. Agħżel l-API key u l-base URL tiegħek
5. Ikklikkja **Applika l-Konfigurazzjoni** jew ikkopja s-snippet tal-konfigurazzjoni manwali

---

### Pass 4 — Issettja l-Varjabbli Globali tal-Ambjent

```bash
# Endpoint Universali ta' OmniRoute
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"
# Gemini CLI jaqra GOOGLE_GEMINI_BASE_URL fl-GĦERQ (l-SDK tiegħu jżid /v1beta/... waħdu)
export GOOGLE_GEMINI_BASE_URL="http://localhost:20128"
export GEMINI_API_KEY="sk-your-omniroute-key"
```

> Għal **server remot** ibdel `localhost:20128` bl-IP jew bid-domain tas-server,
> eż. `http://<your-server-ip>:20128`.

---

### Pass 4 — Ikkonfigura Kull Għodda

#### Claude Code

```bash
# Oħloq ~/.claude/settings.json:
mkdir -p ~/.claude && cat > ~/.claude/settings.json << EOF
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://localhost:20128",
    "ANTHROPIC_AUTH_TOKEN": "sk-your-omniroute-key"
  }
}
EOF
```

Uża l-għerq unifikat tal-gateway ta' Anthropic għal Claude Code. Iżżidx `/v1` hawnhekk.

**Test:** `claude "say hello"`

---

#### OpenAI Codex

Codex modern (v0.137+) jaqra `~/.codex/config.toml` biss — il-
`config.yaml` l-antik jappartjeni għall-CLI npm legacy u jiġi injorat fis-skiet. L-API
key tibqa' fil-varjabbli tal-ambjent `OMNIROUTE_API_KEY` (`env_key`), u qatt
ġewwa l-fajl:

```bash
mkdir -p ~/.codex && cat > ~/.codex/config.toml << EOF
model_provider = "omniroute"

[model_providers.omniroute]
name                 = "OmniRoute"
base_url             = "http://localhost:20128/v1"
env_key              = "OMNIROUTE_API_KEY"
requires_openai_auth = false
EOF
export OMNIROUTE_API_KEY="sk-your-omniroute-key"
```

Referenza sħiħa (profili, `wire_api`, twieqi tal-kuntest): [CODEX-CLI-CONFIGURATION.md](../guides/CODEX-CLI-CONFIGURATION.md).

**Test:** `codex "what is 2+2?"`

---

#### OpenCode

```bash
mkdir -p ~/.config/opencode && cat > ~/.config/opencode/opencode.json << EOF
{
  "\$schema": "https://opencode.ai/config.json",
  "provider": {
    "omniroute": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "OmniRoute",
      "options": {
        "baseURL": "http://localhost:20128/v1",
        "apiKey": "sk-your-omniroute-key"
      },
      "models": {
        "claude-sonnet-4-5": { "name": "claude-sonnet-4-5" },
        "claude-sonnet-4-5-thinking": { "name": "claude-sonnet-4-5-thinking" },
        "gemini-3-flash": { "name": "gemini-3-flash" }
      }
    }
  }
}
EOF
```

**Test:** `opencode`

> Uża `opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high`
> biex tibgħat varjanti tal-ħsieb.

---

#### Cline (CLI jew VS Code)

**Modalità CLI:**

```bash
mkdir -p ~/.cline/data && cat > ~/.cline/data/globalState.json << EOF
{
  "apiProvider": "openai",
  "openAiBaseUrl": "http://localhost:20128/v1",
  "openAiApiKey": "sk-your-omniroute-key"
}
EOF
```

**Modalità VS Code:**
Settings tal-estensjoni Cline → API Provider: `OpenAI Compatible` → Base URL: `http://localhost:20128/v1`

Jew uża d-dashboard ta' OmniRoute → **Għodod CLI → Cline → Applika l-Konfigurazzjoni**.

---

#### KiloCode (CLI jew VS Code)

**Modalità CLI:**

```bash
kilocode --api-base http://localhost:20128/v1 --api-key sk-your-omniroute-key
```

**Settings ta' VS Code:**

```json
{
  "kilo-code.openAiBaseUrl": "http://localhost:20128/v1",
  "kilo-code.apiKey": "sk-your-omniroute-key"
}
```

Jew uża d-dashboard ta' OmniRoute → **Għodod CLI → KiloCode → Applika l-Konfigurazzjoni**.

---

#### Continue (Estensjoni ta' VS Code)

Editja `~/.continue/config.yaml`:

```yaml
models:
  - name: OmniRoute
    provider: openai
    model: auto
    apiBase: http://localhost:20128/v1
    apiKey: sk-your-omniroute-key
    default: true
```

Erġa' ibda VS Code wara li teditja.

---

#### VS Code Insiders (`chatLanguageModels.json`)

Uża dan meta VS Code Insiders ikun ikkonfigurat għal mudelli b'endpoint personalizzat u tkun trid li OmniRoute jaħdem mingħajr field personalizzat tal-header.

**Post rakkomandat:**

- Linux: `~/.config/Code - Insiders/User/chatLanguageModels.json`
- Windows: `%APPDATA%/Code - Insiders/User/chatLanguageModels.json`

**Eżempju bl-użu tal-alias tokenizzat ta’ OmniRoute:**

```json
[
  {
    "vendor": "customendpoint",
    "id": "auto",
    "name": "OmniRoute Auto",
    "family": "gpt-4",
    "version": "1.0.0",
    "url": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/chat/completions",
    "modelsUrl": "http://localhost:20128/api/v1/vscode/sk-your-omniroute-key/models",
    "requestFormat": "openai-chat-completions",
    "contextWindow": 256000,
    "maxOutputTokens": 32768,
    "auth": {
      "type": "none"
    }
  }
]
```

**Noti:**

- Issostitwixxi `sk-your-omniroute-key` b’ċavetta API maħluqa f’OmniRoute.
- Il-field `url` għandu jipponta lejn `/api/v1/vscode/{token}/chat/completions`.
- Il-field `modelsUrl` għandu jipponta lejn `/api/v1/vscode/{token}/models`.
- Agħti preferenza lill-fluss normali ta’ `/v1` + header Bearer meta l-klijent jappoġġja headers personalizzati.
- It-tokens inkorporati fil-URL huma soluzzjoni alternattiva għall-kompatibbiltà u jistgħu jidhru fil-logs tal-editur jew fl-istorja tal-proxy.

---

#### Kiro CLI (Amazon)

```bash
# Idħol fil-kont AWS/Kiro tiegħek:
kiro-cli login

# Is-CLI juża l-awtentikazzjoni tiegħu stess — OmniRoute mhuwiex meħtieġ bħala backend għall-Kiro CLI innifsu.
# Uża kiro-cli flimkien ma’ OmniRoute għal għodod oħra.
kiro-cli status
```

Għall-app tad-desktop **Kiro IDE**, uża l-endpoint MITM espost minn OmniRoute
taħt `/dashboard/cli-tools → Kiro`.

---

## 10. CLI Interna ta’ OmniRoute

Il-binarju `omniroute` jipprovdi kmandi għaċ-ċiklu tal-ħajja tas-server, il-konfigurazzjoni, id-dijanjostika, u l-ġestjoni tal-fornituri. Punt tad-dħul: `bin/omniroute.mjs`.

```bash
omniroute                              # Ibda s-server (port predefinit 20128)
omniroute setup                        # Assistent interattiv tal-konfigurazzjoni
omniroute doctor                       # Iċċekkja l-konfigurazzjoni, id-DB, il-ports, u r-runtime
omniroute providers list               # Konnessjonijiet tal-fornituri kkonfigurati
omniroute providers test-all           # Ittestja kull konnessjoni attiva
omniroute reset-password               # Irrisettja l-password tal-amministratur
omniroute logs                         # Uri r-reġistri tat-talbiet kontinwament
omniroute health                       # Stat tas-saħħa dettaljat (breakers, cache, memorja)
omniroute --version                    # Uri l-verżjoni
omniroute --help                       # Uri l-kmandi kollha
```

### Konfigurazzjoni u Inizjalizzazzjoni

```bash
omniroute setup                        # Assistent interattiv tal-konfigurazzjoni
omniroute setup --non-interactive      # Modalità CI/awtomatizzazzjoni (taqra varjabbli tal-ambjent + flags)
omniroute setup --password '<value>'   # Issettja l-password tal-amministratur direttament
omniroute setup --add-provider \
  --provider openai \
  --api-key '<value>' \
  --test-provider                      # Żid u ttestja fornitur f’pass wieħed
```

Varjabbli tal-ambjent rikonoxxuti għall-konfigurazzjoni mhux interattiva:

| Var                 | Għan                                                                              |
| ------------------- | --------------------------------------------------------------------------------- |
| `OMNIROUTE_API_KEY` | Ċavetta API tal-fornitur (marbuta ma’ `--api-key` permezz ta’ Commander `.env()`) |
| `DATA_DIR`          | Tissostitwixxi d-direttorju tad-data ta’ OmniRoute                                |

L-inputs mhux interattivi l-oħra kollha jiġu mgħoddija bħala flags, mhux bħala varjabbli tal-ambjent:
`--password`, `--provider`, `--provider-name`, `--provider-base-url`, `--default-model`
(ara l-għażliet ta’ `omniroute setup` hawn fuq).

### Dijanjostika

```bash
omniroute doctor                       # Iċċekkja l-konfigurazzjoni, id-DB, il-ports, ir-runtime, il-memorja, u jekk is-server huwiex attiv
omniroute doctor --json                # JSON li jista’ jinqara minn magna
omniroute doctor --no-liveness         # Aqbeż is-sonda HTTP tal-istat tas-saħħa
omniroute doctor --host 0.0.0.0        # Issostitwixxi l-host tal-verifika tal-attività
omniroute doctor --liveness-url <url>  # Issostitwixxi l-URL sħiħ tal-endpoint tal-istat tas-saħħa
```

Id-doctor iwettaq dawn il-kontrolli: `Config`, `Database`, `Storage/encryption`,
`Port availability`, `Node runtime`, `Native binary` (better-sqlite3),
`Memory`, u `Server liveness`. Jintemm b’kodiċi mhux żero jekk xi kontroll ikun `fail`.

### Ġestjoni tal-Fornituri

```bash
omniroute providers available                       # Katalgu tal-fornituri ta’ OmniRoute
omniroute providers available --search openai       # Iffiltra l-katalgu skont l-id/isem/alias/kategorija
omniroute providers available --category api-key    # Iffiltra skont il-kategorija (api-key, oauth, free, ...)
omniroute providers available --json                # JSON li jista’ jinqara minn magna

omniroute providers list                            # Konnessjonijiet tal-fornituri kkonfigurati
omniroute providers list --json

omniroute providers test <id|name>                  # Ittestja konnessjoni kkonfigurata waħda
omniroute providers test-all                        # Ittestja kull konnessjoni attiva
omniroute providers validate                        # Validazzjoni strutturali lokali biss
omniroute providers add <provider> --credential-env PROVIDER_KEY
omniroute providers import ./providers.json --dry-run --json
omniroute providers auth <provider>                 # Fluss OAuth eżistenti
omniroute providers edit <id|name> --default-model <model>
omniroute providers remove <id|name> --yes
```

`providers add/import/auth/edit/remove` jużaw l-API bħala l-ewwel għażla u għalhekk jaħdmu mal-kuntest
lokali jew remot attiv. Għall-input tal-kredenzjali għandhom jintużaw
`--credential-stdin` jew `--credential-env`; `--dry-run --json` jirrapporta biss
il-preżenza/forma b’informazzjoni sensittiva moħbija. `providers available` jaqra l-katalgu ta’ OmniRoute;
`providers list/test/test-all/validate` iżommu l-imġiba SQLite lokali tagħhom u
ma jeħtiġux li s-server ikun qed jaħdem.

Għal node personalizzat kompatibbli ma’ OpenAI jew Anthropic, ehmeż il-kredenzjali mal-
ID tan-node rritornat minn `omniroute nodes add`, billi tuża `omniroute keys add "$NODE_ID" --stdin`.
Dan jeħtieġ server li jkun qed jaħdem u awtentikazzjoni ta’ ġestjoni għall-kuntest attiv.
Is-CLI juża `POST /api/providers`, li jivvalida n-node u jikkopja s-settings tal-endpoint tiegħu
fil-konnessjoni. Node nieqes, falliment fl-awtorizzazzjoni, jew server mhux disponibbli
jirritorna żball mingħajr ma joħloq kredenzjali lokali alternattivi.

`nodes add --base-url` jistabbilixxi l-endpoint tan-node; dan huwa distint mill-indirizz tas-server
f’`OMNIROUTE_BASE_URL`. Għal fajls OpenAPI, uża
`omniroute openapi dump --format json --out ./openapi.json`; l-għażla globali `--output`
tagħżel il-format tal-wiri tas-CLI, mhux isem tal-fajl tad-destinazzjoni.

### Irkupru u Risettjar

```bash
omniroute reset-password                # Irrisettja l-password tal-amministratur (ukoll: omniroute-reset-password)
omniroute reset-encrypted-columns       # Uri twissija + prova mingħajr tibdil għar-risettjar tal-kredenzjali kriptati
omniroute reset-encrypted-columns --force  # Fil-fatt issettja l-kredenzjali kriptati għal null f’SQLite
```

### Esportazzjoni tal-Kredenzjali (⚠ uża b’attenzjoni)

```bash
omniroute auth export                                 # Uri twissija + pass ta’ konferma — ebda aċċess għad-DB
omniroute auth export --force                          # Esporta l-kredenzjali DEKRIPTATI tal-konnessjonijiet KOLLHA lejn stdout bħala JSON
omniroute auth export --force --id <id>                 # Esporta biss il-konnessjoni li taqbel
omniroute auth export --force --format env               # Oħroġ linji OMNIROUTE_<PROVIDER>_<FIELD>=<value>
omniroute auth export --force --out creds.json           # Ikteb f’fajl (maħluq b’permessi 0600)
```

`auth export` huwa **lokali biss** (qari dirett minn SQLite, mingħajr rotta HTTP) u intenzjonalment jistampa/jikteb
il-valuri **f’test sempliċi** ta’ `apiKey`/`accessToken`/`refreshToken`/`idToken` — din hija l-funzjonalità, mhux
bug. Ma jinqara xejn mid-database, u ma jiġi deċifrat xejn, mingħajr `--force`. Banner ta’ twissija fuq stderr
dejjem jiġi stampat qabel ma jinħareġ kwalunkwe test sempliċi. Jeħtieġ li `STORAGE_ENCRYPTION_KEY`
ikun issettjat. Field li ma jirnexxilux jiġi deċifrat (ċavetta skaduta, ciphertext korrott) jiġi rrappurtat bħala
`<field>DecryptFailed: true` minflok ma tiġi abortita l-esportazzjoni kollha jew jiġi żvelat l-iżball sottostanti.

### Sottokmandi oħra

Dawn jassumu li server OmniRoute qed jaħdem, sakemm ma jkunx indikat mod ieħor:

```bash
omniroute status                       # Status komprensiv waqt it-tħaddim
omniroute logs                         # Uri r-reġistri tat-talbiet kontinwament (--json, --search, --follow)
omniroute config list                  # Uri l-għodod CLI kkonfigurati

omniroute provider list                # Elenka l-fornituri disponibbli (alias ta’ providers list)
omniroute provider add                 # Irreġistra OmniRoute bħala fornitur fuq għodda
omniroute keys add | list | remove     # Immaniġġja ċ-ċwievet tal-API
omniroute models [provider]            # Elenka l-mudelli (--json, --search)
omniroute combo list | switch | create | delete

omniroute backup                       # Oħloq snapshot tal-konfigurazzjoni + DB
omniroute restore                      # Irrestawra minn snapshot preċedenti

omniroute health                       # Stat dettaljat tas-saħħa (breakers, cache, memorja)
omniroute quota                        # Użu tal-kwota tal-fornitur
omniroute cache                        # Status tal-cache
omniroute cache clear                  # Żvojta l-caches semantiċi u tal-firem

omniroute mcp status | restart         # Status / startjar mill-ġdid tas-server MCP
omniroute a2a status | card            # Status tas-server A2A / kard tal-aġent

omniroute tunnel list | create | stop  # Immaniġġja t-tunnels (cloudflare/tailscale/ngrok)
omniroute env show | get <k> | set <k> <v>  # Eżamina / issettja l-varjabbli tal-ambjent (temporanji)

omniroute test                         # Test rapidu tal-konnettività tal-fornitur
omniroute update                       # Iċċekkja għal aġġornamenti
omniroute completion                   # Iġġenera l-awtokompletament tax-shell
```

### Flags komuni

| Flag                | Deskrizzjoni                                                |
| ------------------- | ----------------------------------------------------------- |
| `--no-open`         | Tiftaħx il-browser awtomatikament mal-istartjar             |
| `--port <n>`        | Ibdel il-port tal-API (default 20128)                       |
| `--mcp`             | Ħaddem bħala server MCP permezz ta’ stdio (għall-IDEs)      |
| `--non-interactive` | Modalità CI (mingħajr prompts; taqra mill-env/flags)        |
| `--json`            | Output JSON li jinqara mill-magni (doctor, providers, eċċ.) |
| `--help`, `-h`      | Uri għajnuna speċifika għall-kmand                          |
| `--version`, `-v`   | Stampa l-verżjoni installata                                |

---

## Punti tat-Tmiem tal-API Disponibbli

| Punt tat-tmiem             | Deskrizzjoni                         | Uża Għal                          |
| -------------------------- | ------------------------------------ | --------------------------------- |
| `/v1/chat/completions`     | Chat standard (il-fornituri kollha)  | L-għodod moderni kollha           |
| `/v1/responses`            | API tat-tweġibiet (format OpenAI)    | Codex, flussi tax-xogħol aġentiċi |
| `/v1/completions`          | Kompletamenti tat-test tradizzjonali | Għodod eqdem li jużaw `prompt:`   |
| `/v1/embeddings`           | Embeddings tat-test                  | RAG, tiftix                       |
| `/v1/images/generations`   | Ġenerazzjoni tal-immaġnijiet         | GPT-Image, Flux, eċċ.             |
| `/v1/audio/speech`         | Minn test għal diskors               | ElevenLabs, OpenAI TTS            |
| `/v1/audio/transcriptions` | Minn diskors għal test               | Deepgram, AssemblyAI              |

Eżempji lesti biex jitwaħħlu b’URL tokenizzat ta’ OmniRoute:

```txt
Eżempju ta’ token: sk-a3ab3c080beaee3a-69f4a4-070d71af

Bażi standard ta’ OpenAI: http://localhost:20128/v1
Mudelli ta’ VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/models
Chat ta’ VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/chat/completions
Tweġibiet ta’ VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/responses
Tags ta’ Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/tags
Chat ta’ Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/chat
```

---

## Soluzzjoni tal-Problemi

| Żball                                                  | Kawża                         | Soluzzjoni                                                       |
| ------------------------------------------------------ | ----------------------------- | ---------------------------------------------------------------- |
| `Connection refused`                                   | OmniRoute mhux qed jaħdem     | `omniroute serve`                                                |
| `401 Unauthorized`                                     | API key ħażina                | Iċċekkja f’`/dashboard/api-manager`                              |
| `No combo configured`                                  | Ebda combo attiva tar-routing | Ikkonfigura waħda f’`/dashboard/combos`                          |
| Is-CLI juri "not installed"                            | Il-binary mhuwiex fil-PATH    | Iċċekkja `which <command>`                                       |
| Id-dashboard juri "not detected" wara l-installazzjoni | Il-cache mhuwiex aġġornat     | Ikklikkja "⟳ Refresh detection" fid-dashboard                    |
| Link antika `/dashboard/cli-tools`                     | Bookmark ta’ qabel v3.8.6     | Ridirezzjonata awtomatikament lejn `/dashboard/cli-code` (308)   |
| Link antika `/dashboard/agents`                        | Bookmark ta’ qabel v3.8.6     | Ridirezzjonata awtomatikament lejn `/dashboard/acp-agents` (308) |

## Immaniġġja l-politika tal-inference key bis-CLI ta’ OmniRoute

Uża kuntest ta’ ġestjoni awtentikat (ara [Modalità Remota](../guides/REMOTE-MODE.md))
biex tispezzjona jew taġġorna inference key eżistenti permezz tal-ID tagħha:

```bash
omniroute --output json keys policy show KEY_ID
omniroute keys policy set KEY_ID --unrestricted
omniroute --output json keys policy show KEY_ID
```

`--unrestricted` huwa alias għal `--model-access-mode all`. L-aġġornament ineħħi
l-allowlist tal-mudelli. Huwa jippreserva l-ambiti, ir-regoli tal-konnessjoni, il-mudelli
mblukkati, il-limiti tar-rata u l-limiti tal-ispejjeż, għalhekk dawk il-kontrolli l-oħra
xorta jistgħu jirrifjutaw talba. `--allowed-models ""` espliċitu jagħżel ukoll `all`;
għaqqdu ma’ `--model-access-mode restricted` biex iżżomm key ristretta mingħajr mudelli
permessi. Lista mhux vojta separata b’virgoli tagħżel `restricted` sakemm ma jiġix
speċifikat mod ieħor b’mod espliċitu. Kombinazzjoni kontradittorja ta’ `all` flimkien
ma’ allowlist mhux vojta tiġi rrifjutata qabel tintbagħat talba.

`--rate-limit 30` jistabbilixxi t-talbiet kull minuta u jippreserva r-regoli għal perjodi
ta’ żmien oħra. `--max-cost 5` jattiva l-limitu ta’ kuljum f’USD mingħajr ma jibdel
il-limitu ta’ kull ġimgħa; `--max-cost 0` ineħħi l-limitu ta’ kuljum u jippreserva
l-iswiċċ eżistenti tal-limitu tal-użu u l-limitu ta’ kull ġimgħa. Il-fields tal-politika
li jitħallew barra jibqgħu mhux mibdula. Il-bidliet fir-rata l-ewwel jaqraw il-politika
attwali; evita editjar simultanju tal-array tal-limiti tar-rata tal-istess key.

Il-kmandi tal-politika jużaw `GET`/`PATCH /api/keys/{id}` awtentikati u jirrispettaw
il-kuntest attiv u l-għażla globali `--api-key`. L-output JSON fih biss il-fields
tal-politika, mingħajr il-key maħżuna jew ir-rappreżentazzjoni moħbija tagħha.
Kredenzjali għall-inference biss ma tistax tawtorizza bidliet fil-ġestjoni. Żball
401/403 jeħtieġ li jiġu ċċekkjati l-kredenzjali u l-kuntest tal-ġestjoni; dan ma
jistabbilixxix falliment lokali tat-token tas-CLI jew tas-salt. Ara
[Token tas-CLI](../security/CLI_TOKEN.md) għall-kuntratt separat tal-awtentikazzjoni lokali.