CLI Tools — OmniRoute (Português (Brasil))

Como funciona

Códigos de CLI / Agentes de CLI (fluxo de consumo):
Claude / Codex / OpenCode / Cline / KiloCode / Continue / Hermes Agent / Goose / ...
           │
           ▼  (todos apontam para o OmniRoute)
    http://YOUR_SERVER:20128/v1
           │
           ▼  (o OmniRoute encaminha para o provedor correto)
    Anthropic / OpenAI / Gemini / DeepSeek / Groq / Mistral / ...

Agentes ACP (fluxo inverso de inicialização):
    Solicitação do cliente → OmniRoute → inicia a CLI via stdio/ACP → resposta

Benefícios:

• Uma chave de API para gerenciar todas as ferramentas
• Acompanhamento de custos de todas as CLIs no dashboard
• Troca de modelo sem reconfigurar cada ferramenta
• Funciona localmente e em servidores remotos (VPS, Docker, Akamai, Cloudflare Tunnel)

---

Autoconfigurar com setup-*

Você não precisa escrever a configuração de cada ferramenta manualmente. O OmniRoute inclui um comando setup-* por CLI suportado que lê o catálogo de modelos ao vivo de um OmniRoute em execução (local ou remoto) e escreve a própria configuração da ferramenta em sua máquina:

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

Cada um aceita --remote <url> --api-key <key> (configura uma ferramenta local contra um OmniRoute remoto), --dry-run (pré-visualização sem escrita) e --port. Ferramentas sem autodescoberta de modelo (Cline, Kilo, Roo, Goose, Aider, Qwen, 5dive) aceitam --model <id> (e --yes para execuções não interativas). setup-5dive é a única receita que não escreve em $HOME: ele configura uma frota de agentes 5dive escrevendo um perfil de autenticação de propriedade do root no host da frota, então ele re-executa via sudo e não tem seu próprio modo remoto. Para iniciar um CLI com o ambiente correto injetado e nenhuma configuração escrita, use o lançador genérico omniroute run <target> (claude, codex, aider, goose, opencode, qwen, gemini — os alvos e aliases vêm de bin/cli/cli-manifest.mjs); os lançadores legados por ferramenta omniroute launch (Claude Code) e omniroute launch-codex (Codex) permanecem disponíveis. O CLI Gemini é apenas para lançamento: é um alvo de omniroute run mas não tem uma receita setup-*/configure.

Referência completa: a tabela mestra — o que cada comando escreve, cada flag, local vs remoto, e quais ferramentas precisam de um sufixo /v1 — está em Integrações CLI.

Executando-os dentro de um contêiner

Um comando setup-* executado dentro do contêiner OmniRoute escreve no diretório home do próprio contêiner, que nenhum CLI do host lê e que desaparece com o contêiner. O OmniRoute detecta isso e sai com 2 e instruções, em vez de escrever. Duas formas suportadas de prosseguir — instale o CLI no host e omniroute connect ao contêiner, ou monte os diretórios de configuração (bind-mount) e defina CLI_CONFIG_HOME (o perfil host do compose). Todo comando setup-*, além de omniroute configure e omniroute config set, aceita --allow-container-write quando configurar os próprios CLIs do contêiner é o que você realmente pretendia; OMNIROUTE_ALLOW_CONTAINER_CONFIG_WRITE=true faz o mesmo para o servidor. Veja Guia Docker → Configurando ferramentas CLI do host.

O endpoint de aplicação do painel (POST /api/cli-tools/apply) impõe a mesma proteção: em um contêiner, uma escrita cujo alvo não está montado (bind-mounted) a partir do host responde 422 com containerEphemeralTarget: true, o texto de erro seguro e — para as ferramentas com uma receita de host (claude, codex, opencode, cline, kilo, continue) — um hostSetupCommand (ex: omniroute setup-opencode) para ser executado no host; nada é escrito. dryRun: true continua funcionando no modo contêiner e retorna uma pré-visualização redigida + caminho de destino sem tocar no disco. O conteúdo da pré-visualização não é uma configuração contendo credenciais para copiar ou importar. Aplique com a ferramenta original/URL base/chave API/entradas de modelo no host, ou use o comando de configuração indicado no lado do host. Veja segurança da configuração CLI para o cabeçalho da pré-visualização e o contrato da requisição. Este comportamento é intencional e protegido contra regressão por tests/unit/api/cli-tools/apply-container-guard.test.ts — nunca “corrija” um 422 removendo a proteção.

---

Fonte da verdade

O catálogo unificado fica em src/shared/constants/cliTools.ts como CLI_TOOLS: Record<string, CliCatalogEntry>.

Cada entrada possui estes campos (definidos em src/shared/schemas/cliCatalog.ts):

Campo	Tipo	Descrição
category	"code" | "agent"	Em qual página a ferramenta aparece
vendor	string	Origem da ferramenta (“Anthropic”, “OSS (P. Gauthier)”)
acpSpawnable	boolean	Também pode ser usada como um Agente ACP (selo exibido)
baseUrlSupport	"full" | "partial" | "none"	Nível de suporte a endpoint personalizado. "none" = pendência de MITM
configType	"env" | "custom" | "guide" | "custom-builder" | "mitm"	Mecanismo de configuração
id, name, color, description, docsUrl	padrão	Campos principais de exibição

As entradas com baseUrlSupport: "none" não são exibidas nas páginas do painel — elas são registradas na lista de pendências de MITM do plano 11 (consulte _tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md).

Níveis de capacidade (catalogável × detectável × configurável × executável)

Nem toda ferramenta catalogada é detectável, configurável ou executável. Cada nível possui uma única fonte declarativa, e um teste de divergência os mantém alinhados:

Nível	Significado	Declarado em
Catalogável	Aparece no catálogo do painel (nome, fornecedor, documentação, tipo de configuração)	src/shared/constants/cliTools.ts (CLI_TOOLS)
Detectável	Detecção de binário/configuração, verificações de integridade, caminhos de configuração	src/shared/services/cliRuntime.ts (catálogo de runtime CLI_TOOLS)
Configurável	Compatível com omniroute configure <cli> (existe uma receita de configuração)	bin/cli/cli-manifest.mjs (configure: true)
Executável	Compatível com omniroute run <target> (injeção de env/argumentos definida)	bin/cli/cli-manifest.mjs (run: true)

bin/cli/cli-manifest.mjs é o manifesto executável canônico para as interfaces de comando da CLI: run, configure e os geradores de conclusão de shell derivam dele suas listas de destinos, a resolução de aliases (por exemplo, kilocode/kilo-code/kilo_cli → kilo) e a configuração da flag --model. A proteção contra divergências tests/unit/cli/cli-manifest-drift.test.ts verifica se o manifesto, o catálogo de runtime, o catálogo da interface e cada superfície consumidora permanecem sincronizados — um destino adicionado a uma superfície sem as demais faz a suíte falhar, em vez de permitir uma divergência silenciosa.

---

1. Catálogo de Código CLI (26 ferramentas)

Todas as ferramentas que aparecem em /dashboard/cli-code. Aquelas com baseUrlSupport: none são conectadas via MITM ou um guia manual em vez de uma URL base personalizada:

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

Ferramentas com baseUrlSupport: "partial" exibem um selo “⚠ Base URL parcial” no cartão do painel.

2. Catálogo de agentes CLI (10 ferramentas)

Agentes autônomos que aparecem em /dashboard/cli-agents:

id	nome	fornecedor	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. Agentes ACP (/dashboard/acp-agents)

Esta página (renomeada de /dashboard/agents) mostra CLIs que o OmniRoute pode iniciar como mecanismos de execução de backend por meio do protocolo stdio/ACP. O catálogo é mantido separadamente em src/lib/acp/registry.ts e não é igual a CLI_TOOLS.

---

4. Backlog de MITM (não exibido no painel)

As CLIs a seguir não oferecem suporte nativo a uma URL base personalizada e não estão listadas nas páginas CLI Code ou CLI Agents. Elas são candidatas à interceptação MITM no plano 11:

CLI	Motivo
windsurf	BYOK limitado a modelos Claude selecionados + URL/token corporativo
amp	Ecossistema fechado (Sourcegraph)
amazon-q / kiro-cli	Autenticação por AWS SSO, sem URL personalizada
cowork	Anthropic Desktop, sem endpoint configurável

Consulte _tasks/features-v3.8.6/refactorpages/_orchestration/_plan11-mitm-backlog.md para obter a referência cruzada completa.

---

5. API de detecção em lote

Toda a detecção de ferramentas é agregada por meio de um único endpoint:

GET /api/cli-tools/all-statuses

• Autenticação: requireCliToolsAuth(request) (igual às outras rotas de /api/cli-tools/)
• Retorna: Record<toolId, ToolBatchStatus> (tipo: src/shared/types/cliBatchStatus.ts)
• Estratégia: Promise.all para todas as ferramentas, com timeout de 5s por ferramenta
• Cache: LRU em memória indexado pelo mtime do arquivo de configuração. O cache é invalidado quando o mtime muda. Redefinido quando o servidor é reiniciado.

Formato da resposta por ferramenta:

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; // sanitizado, sem rastreamentos de pilha
}

---

6. Manipuladores de Configurações para Novas Ferramentas

Novas ferramentas com configType: "custom" têm rotas de API de configurações dedicadas:

Rota	Ferramenta
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, legado)
POST /api/cli-tools/codewhale-settings	CodeWhale (OPENAI_BASE_URL, sincronização principal + legada com ~/.deepseek)
POST /api/cli-tools/smelt-settings	Smelt
POST /api/cli-tools/pi-settings	Agente de programação 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 + chave dedicada no .env)

Todas as rotas usam sanitizeErrorMessage() para respostas de erro (Regra Rígida nº 12).

---

7. Arquitetura das Páginas do Painel

CLI Code (/dashboard/cli-code)

• src/app/(dashboard)/dashboard/cli-code/page.tsx — componente de servidor
• src/app/(dashboard)/dashboard/cli-code/CliCodePageClient.tsx — grade do cliente
• src/app/(dashboard)/dashboard/cli-code/[id]/page.tsx — página de detalhes da ferramenta
• src/app/(dashboard)/dashboard/cli-code/components/ — 12 cartões especializados de ferramentas + ToolDetailClient.tsx

Agentes CLI (/dashboard/cli-agents)

• src/app/(dashboard)/dashboard/cli-agents/page.tsx — componente de servidor
• src/app/(dashboard)/dashboard/cli-agents/CliAgentsPageClient.tsx — grade do cliente
• src/app/(dashboard)/dashboard/cli-agents/[id]/page.tsx — reutiliza ToolDetailClient

Agentes ACP (/dashboard/acp-agents)

• src/app/(dashboard)/dashboard/acp-agents/page.tsx — componente de servidor (movido de agents/)

Componentes de UI Compartilhados (src/shared/components/cli/)

Arquivo	Finalidade
CliToolCard.tsx	Cartão de status inteligente (detecção + configuração + endpoint)
CliConceptCard.tsx	Cartão de explicação de conceitos por página
CliComparisonCard.tsx	Comparação em três colunas entre os tipos de CLI
BaseUrlSelect.tsx	Lista suspensa de endpoints (Local/Nuvem/Personalizado)
ApiKeySelect.tsx	Seletor de chave de API
ManualConfigModal.tsx	Modal com trecho de configuração copiável

Hook Compartilhado (src/shared/hooks/cli/)

Arquivo	Finalidade
useToolBatchStatuses.ts	Busca /api/cli-tools/all-statuses e gerencia o estado de carregamento/atualização

---

8. i18n

Novos namespaces adicionados no plano 14 F9:

Namespace	Finalidade
cliCommon	Strings compartilhadas (rótulos de cartões, textos de conceitos/comparações, rótulos da página de detalhes)
cliCode	Strings da página CLI Code
cliAgents	Strings da página CLI Agents
acpAgents	Strings da página ACP Agents

São fornecidas traduções completas para PT-BR e EN. Os outros 39 idiomas usam automaticamente EN como fallback por meio da mesclagem no nível do namespace em src/i18n/request.ts.

---

9. Início Rápido

Etapa 1 — Obtenha uma chave de API do OmniRoute

1. Abra /dashboard/api-manager → Criar chave de API
2. Dê um nome a ela (por exemplo, cli-tools) e selecione todas as permissões
3. Copie a chave — você precisará dela para cada CLI abaixo

Sua chave tem esta aparência: sk-xxxxxxxxxxxxxxxx-xxxxxxxxx

---

Etapa 2 — Instale as ferramentas de CLI

Todas as ferramentas baseadas em npm exigem Node.js 22.22.2+ ou 24.x:

# 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 (pode ser iniciado por meio de `omniroute run gemini` → superfície /v1beta)
npm install -g @google/gemini-cli

# Aider
pip install aider-chat

# Smelt
cargo install smelt  # Baseado em Rust

# Agente de programação Pi
# consulte https://github.com/zechnerj/pi-coding-agent para obter instruções de instalação

# jcode
# consulte https://github.com/1jehuang/jcode para obter instruções de instalação

---

Etapa 3 — Configure por meio do painel

1. Acesse http://localhost:20128/dashboard/cli-code
2. Encontre sua ferramenta na grade
3. Clique no cartão para abrir a página de detalhes da ferramenta
4. Selecione sua chave de API e a URL base
5. Clique em Aplicar configuração ou copie o trecho de configuração manual

---

Etapa 4 — Defina variáveis de ambiente globais

# Endpoint universal do 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"
# O Gemini CLI lê GOOGLE_GEMINI_BASE_URL na RAIZ (o próprio SDK acrescenta /v1beta/...)
export GOOGLE_GEMINI_BASE_URL="http://localhost:20128"
export GEMINI_API_KEY="sk-your-omniroute-key"

Para um servidor remoto, substitua localhost:20128 pelo IP ou domínio do servidor, por exemplo, http://<your-server-ip>:20128.

---

Etapa 4 — Configure cada ferramenta

Claude Code

# Crie ~/.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

Use a raiz unificada do gateway da Anthropic para o Claude Code. Não acrescente /v1 aqui.

Teste: claude "say hello"

---

OpenAI Codex

O Codex moderno (v0.137+) lê apenas ~/.codex/config.toml — o antigo config.yaml pertence à CLI npm legada e é ignorado silenciosamente. A chave da API permanece na variável de ambiente OMNIROUTE_API_KEY (env_key), nunca dentro do arquivo:

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"

Referência completa (perfis, wire_api, janelas de contexto): CODEX-CLI-CONFIGURATION.md.

Teste: codex "what is 2+2?"

---

OpenCode

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

Teste: opencode

Use opencode run "your prompt" --model omniroute/claude-sonnet-4-5-thinking --variant high para enviar variantes de raciocínio.

---

Cline (CLI ou VS Code)

Modo CLI:

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

Modo VS Code: Configurações da extensão Cline → Provedor de API: OpenAI Compatible → URL base: http://localhost:20128/v1

Ou use o painel do OmniRoute → Ferramentas de CLI → Cline → Aplicar configuração.

---

KiloCode (CLI ou VS Code)

Modo CLI:

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

Configurações do VS Code:

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

Ou use o painel do OmniRoute → Ferramentas de CLI → KiloCode → Aplicar configuração.

---

Continue (extensão do VS Code)

Edite ~/.continue/config.yaml:

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

Reinicie o VS Code após editar.

---

VS Code Insiders (chatLanguageModels.json)

Use esta opção quando o VS Code Insiders estiver configurado para modelos de endpoint personalizados e você quiser que o OmniRoute funcione sem um campo de cabeçalho personalizado.

Local recomendado:

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

Exemplo usando o alias tokenizado do OmniRoute:

[
  {
    "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"
    }
  }
]

Observações:

• Substitua sk-your-omniroute-key por uma chave de API criada no OmniRoute.
• O campo url deve apontar para /api/v1/vscode/{token}/chat/completions.
• O campo modelsUrl deve apontar para /api/v1/vscode/{token}/models.
• Prefira o fluxo normal com /v1 + cabeçalho Bearer quando o cliente oferecer suporte a cabeçalhos personalizados.
• Tokens incorporados à URL são uma alternativa de compatibilidade e podem aparecer nos logs do editor ou no histórico do proxy.

---

Kiro CLI (Amazon)

# Faça login na sua conta AWS/Kiro:
kiro-cli login

# A CLI usa sua própria autenticação — o OmniRoute não é necessário como backend para a própria Kiro CLI.
# Use kiro-cli junto com o OmniRoute para outras ferramentas.
kiro-cli status

Para o aplicativo desktop Kiro IDE, use o endpoint MITM disponibilizado pelo OmniRoute em /dashboard/cli-tools → Kiro.

---

10. CLI interna do OmniRoute

O binário omniroute fornece comandos para ciclo de vida do servidor, configuração, diagnóstico e gerenciamento de provedores. Ponto de entrada: bin/omniroute.mjs.

omniroute                              # Inicia o servidor (porta padrão 20128)
omniroute setup                        # Assistente de configuração interativo
omniroute doctor                       # Verifica configuração, banco de dados, portas e ambiente de execução
omniroute providers list               # Conexões de provedores configuradas
omniroute providers test-all           # Testa todas as conexões ativas
omniroute reset-password               # Redefine a senha de administrador
omniroute logs                         # Transmite logs de requisições
omniroute health                       # Integridade detalhada (disjuntores, cache, memória)
omniroute --version                    # Exibe a versão
omniroute --help                       # Exibe todos os comandos

Configuração e inicialização

omniroute setup                        # Assistente de configuração interativo
omniroute setup --non-interactive      # Modo de CI/automação (lê variáveis de ambiente + flags)
omniroute setup --password '<value>'   # Define diretamente a senha de administrador
omniroute setup --add-provider \
  --provider openai \
  --api-key '<value>' \
  --test-provider                      # Adiciona e testa um provedor em uma única operação

Variáveis de ambiente reconhecidas para configuração não interativa:

Var	Finalidade
OMNIROUTE_API_KEY	Chave de API do provedor (vinculada a --api-key por meio de .env() do Commander)
DATA_DIR	Substitui o diretório de dados do OmniRoute

Todas as outras entradas não interativas são passadas como flags, não como variáveis de ambiente: --password, --provider, --provider-name, --provider-base-url, --default-model (consulte as opções de omniroute setup acima).

Diagnóstico

omniroute doctor                       # Verifica configuração, banco de dados, portas, ambiente de execução, memória e atividade
omniroute doctor --json                # JSON legível por máquina
omniroute doctor --no-liveness         # Ignora a sondagem de integridade HTTP
omniroute doctor --host 0.0.0.0        # Substitui o host da verificação de atividade
omniroute doctor --liveness-url <url>  # Substitui a URL completa do endpoint de integridade

O doctor executa estas verificações: Config, Database, Storage/encryption, Port availability, Node runtime, Native binary (better-sqlite3), Memory e Server liveness. Ele encerra com um código diferente de zero se alguma verificação resultar em fail.

Gerenciamento de provedores

omniroute providers available                       # Catálogo de provedores do OmniRoute
omniroute providers available --search openai       # Filtra o catálogo por id/nome/alias/categoria
omniroute providers available --category api-key    # Filtra por categoria (api-key, oauth, free, ...)
omniroute providers available --json                # JSON legível por máquina

omniroute providers list                            # Conexões de provedores configuradas
omniroute providers list --json

omniroute providers test <id|name>                  # Testa uma conexão configurada
omniroute providers test-all                        # Testa todas as conexões ativas
omniroute providers validate                        # Validação estrutural somente local
omniroute providers add &lt;provider&gt; --credential-env PROVIDER_KEY
omniroute providers import ./providers.json --dry-run --json
omniroute providers auth &lt;provider&gt;                 # Fluxo OAuth existente
omniroute providers edit <id|name> --default-model &lt;model&gt;
omniroute providers remove <id|name> --yes

providers add/import/auth/edit/remove usam prioritariamente a API e, portanto, funcionam no contexto ativo, seja ele local ou remoto. A entrada de credenciais deve usar --credential-stdin ou --credential-env; --dry-run --json relata apenas a presença/estrutura com dados sensíveis ocultados. providers available lê o catálogo do OmniRoute; providers list/test/test-all/validate mantêm seu comportamento de SQLite local e não exigem que o servidor esteja em execução.

Recuperação e redefinição

omniroute reset-password                # Redefine a senha de administrador (também: omniroute-reset-password)
omniroute reset-encrypted-columns       # Exibe um aviso + simulação da redefinição de credenciais criptografadas
omniroute reset-encrypted-columns --force  # Efetivamente define como nulas as credenciais criptografadas no SQLite

Exportação de credenciais (⚠ manuseie com cuidado)

omniroute auth export                                 # Exibe aviso + solicitação de confirmação — sem acesso ao banco de dados
omniroute auth export --force                          # Exporta as credenciais DESCRIPTOGRAFADAS de TODAS as conexões para stdout como JSON
omniroute auth export --force --id <id>                 # Exporta apenas a conexão correspondente
omniroute auth export --force --format env               # Emite linhas OMNIROUTE_<PROVIDER>_<FIELD>=&lt;value&gt;
omniroute auth export --force --out creds.json           # Grava em um arquivo (criado com permissões 0600)

auth export funciona somente localmente (leitura direta do SQLite, sem rota HTTP) e, intencionalmente, exibe/grava valores de apiKey/accessToken/refreshToken/idToken em texto simples — esse é o recurso, não um bug. Nada é lido do banco de dados e nada é descriptografado sem --force. Um banner de aviso em stderr é sempre exibido antes que qualquer texto simples seja emitido. Exige que STORAGE_ENCRYPTION_KEY esteja definida. Um campo cuja descriptografia falhar (chave obsoleta, texto cifrado corrompido) será relatado como <field>DecryptFailed: true, em vez de interromper toda a exportação ou expor o erro subjacente.

Outros subcomandos

Eles pressupõem que um servidor OmniRoute esteja em execução, salvo indicação em contrário:

omniroute status                       # Status abrangente do ambiente de execução
omniroute logs                         # Transmitir logs de requisições (--json, --search, --follow)
omniroute config list                  # Exibir ferramentas de CLI configuradas

omniroute provider list                # Listar provedores disponíveis (alias de providers list)
omniroute provider add                 # Registrar o OmniRoute como provedor em uma ferramenta
omniroute keys add | list | remove     # Gerenciar chaves de API
omniroute models [provider]            # Listar modelos (--json, --search)
omniroute combo list | switch | create | delete

omniroute backup                       # Criar snapshot da configuração + banco de dados
omniroute restore                      # Restaurar a partir de um snapshot anterior

omniroute health                       # Integridade detalhada (disjuntores, cache, memória)
omniroute quota                        # Uso da cota do provedor
omniroute cache                        # Status do cache
omniroute cache clear                  # Limpar caches semântico e de assinaturas

omniroute mcp status | restart         # Status / reinicialização do servidor MCP
omniroute a2a status | card            # Status do servidor A2A / cartão do agente

omniroute tunnel list | create | stop  # Gerenciar túneis (cloudflare/tailscale/ngrok)
omniroute env show | get <k> | set <k> <v>  # Inspecionar / definir variáveis de ambiente (temporárias)

omniroute test                         # Teste rápido de conectividade do provedor
omniroute update                       # Verificar atualizações
omniroute completion                   # Gerar autocompletar do shell

Opções comuns

Opção	Descrição
--no-open	Não abrir automaticamente o navegador ao iniciar
--port <n>	Substituir a porta da API (padrão: 20128)
--mcp	Executar como servidor MCP via stdio (para IDEs)
--non-interactive	Modo de CI (sem prompts; lê de variáveis de ambiente/opções)
--json	Saída JSON legível por máquina (doctor, providers etc.)
--help, -h	Exibir a ajuda específica do comando
--version, -v	Exibir a versão instalada

---

Endpoints de API disponíveis

Endpoint	Descrição	Usado para
/v1/chat/completions	Chat padrão (todos os provedores)	Todas as ferramentas modernas
/v1/responses	API Responses (formato da OpenAI)	Codex, fluxos de trabalho com agentes
/v1/completions	Preenchimentos de texto legados	Ferramentas antigas que usam prompt:
/v1/embeddings	Embeddings de texto	RAG, pesquisa
/v1/images/generations	Geração de imagens	GPT-Image, Flux etc.
/v1/audio/speech	Conversão de texto em fala	ElevenLabs, TTS da OpenAI
/v1/audio/transcriptions	Conversão de fala em texto	Deepgram, AssemblyAI

Exemplos prontos para colar com uma URL tokenizada do OmniRoute:

Exemplo de token: sk-a3ab3c080beaee3a-69f4a4-070d71af

Base padrão da OpenAI: http://localhost:20128/v1
Modelos do VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/models
Chat do VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/chat/completions
Responses do VS Code: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/responses
Tags do Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/tags
Chat do Ollama: http://localhost:20128/api/v1/vscode/sk-a3ab3c080beaee3a-69f4a4-070d71af/api/chat

---

Solução de problemas

Erro	Causa	Solução
Connection refused	O OmniRoute não está em execução	omniroute serve
401 Unauthorized	Chave de API incorreta	Verifique em /dashboard/api-manager
No combo configured	Nenhum combo de roteamento ativo	Configure em /dashboard/combos
A CLI mostra “not installed”	O binário não está no PATH	Verifique com which <command>
O painel mostra “not detected” após a instalação	Cache desatualizado	Clique em “⟳ Atualizar detecção” no painel
Link antigo /dashboard/cli-tools	Favorito anterior à v3.8.6	Redirecionado automaticamente para /dashboard/cli-code (308)
Link antigo /dashboard/agents	Favorito anterior à v3.8.6	Redirecionado automaticamente para /dashboard/acp-agents (308)

---

Código-fonte do OmniRoute (a58000c7685f)