Pular para o conteúdo principal
Se você estiver executando o Kodus na sua própria infraestrutura, o CLI funciona da mesma forma — você só precisa apontá-lo para a sua API.

​
Conectar à Sua Instância

1

Definir a URL da API

Informe ao CLI onde sua API do Kodus está. Escolha um método:
export KODUS_API_URL=https://kodus-api.suaempresa.com
Adicione isso ao seu perfil de shell (~/.bashrc, ~/.zshrc, etc.) para torná-lo permanente:
echo 'export KODUS_API_URL=https://kodus-api.suaempresa.com' >> ~/.zshrc
source ~/.zshrc
HTTPS é obrigatório. O CLI rejeita URLs não-HTTPS por segurança. A única exceção é localhost e 127.0.0.1 para desenvolvimento local.
Ordem de prioridade: Variável de ambiente KODUS_API_URL > apiUrl em ~/.kodus/config.json > padrão (https://api.kodus.io).
2

Autenticar

Gere uma chave de equipe no painel do Kodus self-hosted e configure-a:
kodus auth team-key --key kodus_xxxxx
Ou use o instalador com a URL da API e a chave de equipe:
curl -fsSL https://review-skill.com/install | bash -s -- --team-key kodus_xxxxx
Chaves de equipe são ideais para ambientes compartilhados e configurações de agentes de IA — sem necessidade de login individual.
3

Verificar a Conexão

kodus auth status
Você deve ver seu modo de autenticação, nome da organização e que o token é válido. No modo verbose, a URL da API em uso é registrada:
kodus auth status --verbose

​
Cloudflare Access (Zero Trust)

Se sua API self-hosted estiver atrás do Cloudflare Access, o CLI suporta autenticação via service token. 
export KODUS_API_URL=https://kodus-api.suaempresa.com
export CF_ACCESS_CLIENT_ID=seu-client-id.access
export CF_ACCESS_CLIENT_SECRET=seu-client-secret
O CLI envia os headers CF-Access-Client-Id e CF-Access-Client-Secret em cada requisição de API quando configurados. Prioridade: variáveis de ambiente > arquivo de configuração.

​
Referência do Arquivo de Configuração

O CLI armazena a configuração em ~/.kodus/config.json: 
{
  "apiUrl": "https://kodus-api.suaempresa.com",
  "teamKey": "kodus_xxxxx",
  "teamName": "Engineering",
  "organizationName": "Acme Corp",
  "cfAccessClientId": "seu-client-id.access",
  "cfAccessClientSecret": "seu-client-secret"
}
CampoObrigatórioDescrição
apiUrlNãoSua URL de API self-hosted. Substituída pela variável de ambiente KODUS_API_URL.
teamKeyNãoChave de API da equipe (começa com kodus_). Substituída pela variável de ambiente KODUS_TEAM_KEY.
teamNameNãoNome de exibição para a equipe.
organizationNameNãoNome de exibição para a organização.
cfAccessClientIdNãoID do cliente Cloudflare Access. Substituído pela variável de ambiente CF_ACCESS_CLIENT_ID.
cfAccessClientSecretNãoSegredo do cliente Cloudflare Access. Substituído pela variável de ambiente CF_ACCESS_CLIENT_SECRET.
O arquivo de configuração é criado com permissões 0600 (apenas leitura/escrita pelo proprietário). O diretório ~/.kodus/ é criado com permissões 0700.

​
Resumo das Variáveis de Ambiente

VariávelDescrição
KODUS_API_URLEndpoint da API self-hosted (HTTPS obrigatório, exceto localhost)
KODUS_TEAM_KEYChave de equipe para acesso compartilhado
KODUS_TOKENToken CI/CD para pipelines
CF_ACCESS_CLIENT_IDID do cliente Cloudflare Access
CF_ACCESS_CLIENT_SECRETSegredo do cliente Cloudflare Access
KODUS_VERBOSEDefina como true para ver a URL de API resolvida e detalhes das requisições

​
Integração CI/CD

Para instâncias self-hosted em pipelines CI/CD, defina a URL da API e a autenticação como variáveis de ambiente: 
- name: Kodus Review
  env:
    KODUS_API_URL: ${{ secrets.KODUS_API_URL }}
    KODUS_TEAM_KEY: ${{ secrets.KODUS_TEAM_KEY }}
  run: npx @kodus/cli review --format json --fail-on error
Use --fail-on error ou --fail-on critical para falhar o pipeline quando problemas acima de um limite de severidade forem encontrados.

​
Distribuindo para Sua Equipe

Para integrar sua equipe em um único comando, combine a URL da API com o instalador de skills: 
KODUS_API_URL=https://kodus-api.suaempresa.com \
  curl -fsSL https://review-skill.com/install | bash -s -- --team-key kodus_xxxxx
Isso instala o CLI, configura a chave de equipe e implanta skills de revisão nos agentes de IA detectados (Claude Code, Cursor, Windsurf) — todos apontando para a sua instância self-hosted.

​
Solução de Problemas

O CLI exige HTTPS para todas as URLs não-localhost. Certifique-se de que sua instância self-hosted tem um certificado TLS válido. Se estiver testando localmente, use http://localhost:<porta>.
  • Verifique se a URL está acessível: curl -I https://kodus-api.suaempresa.com
  • Verifique se um firewall ou VPN está bloqueando a conexão
  • Se estiver atrás do Cloudflare Access, certifique-se de que CF_ACCESS_CLIENT_ID e CF_ACCESS_CLIENT_SECRET estão definidos
  • Use --verbose para ver a URL exata sendo usada
  • Execute kodus auth status para verificar seu estado de autenticação atual
  • Se estiver usando uma chave de equipe, verifique se ela ainda é válida no painel self-hosted
  • Se estiver usando login pessoal, os tokens expiram após 1 hora — o CLI atualiza automaticamente, mas pode ser necessário fazer login novamente se o token de refresh também tiver expirado
  • Certifique-se de que KODUS_API_URL aponta para a instância correta
Isso geralmente significa que a URL está atingindo um proxy reverso, balanceador de carga ou página do Cloudflare Access em vez da API real. Verifique:
  • O caminho da URL está correto (sem /api ou similar no final)
  • As credenciais do Cloudflare Access estão configuradas, se aplicável
  • O proxy reverso está encaminhando as requisições corretamente
Sua instância self-hosted pode impor limites de dispositivos por organização. Entre em contato com seu administrador para aumentar o limite ou remover dispositivos antigos do painel.