O ChatCLI é amplamente configurável através de variáveis de ambiente. A maneira mais fácil de gerenciá-las é criando um arquivo .env na raiz do seu projeto ou no seu diretório HOME.

A ordem de prioridade para as configurações é:

  1. Flags de linha de comando (ex: --provider)
  2. Variáveis de Ambiente do Sistema
  3. Variáveis no arquivo .env
  4. Valores Padrão

Configuração Geral

VariávelDescriçãoPadrão
ENVDefine o ambiente, caso dev os logs são mostrados no terminal e salvo no log da app, caso prod somente no log. Valores válidos: dev, proddev
LLM_PROVIDERDefine o provedor de IA padrão a ser usado. Valores válidos: OPENAI, CLAUDEAI, GOOGLEAI, XAI, OLLAMA, STACKSPOT."OPENAI"
CHATCLI_LANGDefine o idioma da interface. Valores: pt-BR, en-US. Se não definida, tentará detectar o idioma do sistema.en-US
LOG_LEVELNível dos logs. Opções: debug, info, warn, error."info"
LOG_FILECaminho para o arquivo de log. Padrão: $HOME/.chatcli/app.log"$HOME/.chatcli/app.log"
LOG_MAX_SIZETamanho máximo do arquivo de log antes da rotação. Aceita 100MB, 50KB, etc."100MB"
HISTORY_MAX_SIZETamanho máximo do arquivo de histórico (.chatcli_history) antes da rotação."100MB"
HISTORY_FILECaminho personalizado para o arquivo de histórico (suporta ~, hoje ele cria o histórico onde executou o chatcli).".chatcli_history"
CHATCLI_DOTENVCaminho personalizado para o seu arquivo .env.".env"
CHATCLI_IGNORECaminho para arquivo de ignore (ex.: .chatignore). Quando definido, ele tem prioridade sobre o ignore do projeto/global.""
CHATCLI_CODER_UIEstilo da UI do modo /coder: full (padrão) ou mínimal."full"
CHATCLI_CODER_BANNERExibe o cheat sheet rápido do /coder na entrada da sessão (true/false)."true"

Autenticação OAuth

Além das chaves de API tradicionais, o ChatCLI suporta autenticação via OAuth para OpenAI e Anthropic. Com o OAuth, você pode usar seu plano existente (ChatGPT Plus, Codex, Claude Pro) sem gerar API keys.

VariávelDescriçãoPadrão
CHATCLI_AUTH_DIRDiretório onde as credenciais OAuth são armazenadas.~/.chatcli/
CHATCLI_OPENAI_CLIENT_IDPermite sobrescrever o client ID do OAuth da OpenAI.(interno)

As credenciais são armazenadas com criptografia AES-256-GCM em ~/.chatcli/auth-profiles.json. A chave de criptografia é gerada automaticamente e salva em ~/.chatcli/.auth-key (permissão 0600).

Use /auth login openai-codex ou /auth login anthropic no modo interativo para iniciar o fluxo OAuth. Consulte a documentação completa de OAuth para mais detalhes.

Configuração de Provedores

OpenAI

VariávelDescriçãoObrigatório?
OPENAI_API_KEYSua chave de API secreta da OpenAI. Alternativa: use /auth login openai-codex para OAuth.Sim*
OPENAI_MODELO modelo a ser usado. Ex: gpt-4o, gpt-4o-mini, gpt-4-turbo.Não
OPENAI_ASSISTANT_MODELO modelo a ser usado específicamente para a API de Assistentes.Não
OPENAI_USE_RESPONSESDefine true para usar a API de v1/responses em vez de v1/chat/completions.Não
OPENAI_MAX_TOKENSDefine o maximo de tokens a ser utilizados na sessão (depende do modelo)Não

Anthropic (Claude)

VariávelDescriçãoObrigatório?
ANTHROPIC_API_KEYSua chave de API secreta da Anthropic. Alternativa: use /auth login anthropic para OAuth.Sim*
ANTHROPIC_MODELO modelo a ser usado. Ex: claude-sonnet-4-5, claude-opus-4-6, claude-sonnet-4.Não
ANTHROPIC_API_VERSIONA versão da API da Anthropic a ser usada nos cabeçalhos.Não
ANTHROPIC_MAX_TOKENSDefine o maximo de tokens a ser utilizados na sessão (depende do modelo)Não

Google (Gemini)

VariávelDescriçãoObrigatório?
GOOGLEAI_API_KEYSua chave de API do Google AI Studio.Sim
GOOGLEAI_MODELO modelo a ser usado. Ex: gemini-2.5-pro, gemini-2.5-flash.Não
GOOGLEAI_MAX_TOKENSDefine o maximo de tokens a ser utilizados na sessão (depende do modelo)Não

xAI (Grok)

VariávelDescriçãoObrigatório?
XAI_API_KEYSua chave de API secreta da xAI.Sim
XAI_MODELO modelo a ser usado. Ex: grok-4-fast, grok-3.Não
XAI_MAX_TOKENSDefine o maximo de tokens a ser utilizados na sessão (depende do modelo)Não

Ollama (Local)

VariávelDescriçãoObrigatório?
OLLAMA_ENABLEDDefina como true para habilitar o provedor Ollama.Sim
OLLAMA_BASE_URLURL base do seu servidor Ollama local.Não
OLLAMA_MODELO nome do modelo local a ser usado (ex: llama3, codellama).Não
OLLAMA_FILTER_THINKINGFiltra raciocínio intermediário em respostas (ex.: para Qwen3, llama3 padrão true…).Não
OLLAMA_MAX_TOKENSDefine o máximo de tokens para o provedor Ollama.Não

StackSpot

VariávelDescriçãoObrigatório?
CLIENT_IDCredencial de ID de cliente da StackSpot.Sim
CLIENT_KEYCredencial de chave de cliente da StackSpot.Sim
STACKSPOT_REALMO realm (tenant) da sua organização na StackSpot.Sim
STACKSPOT_AGENT_IDO ID do agente específico a ser utilizado.Sim

* Para OpenAI e Anthropic, a chave de API é obrigatória apenas se você não utilizar autenticação OAuth (/auth login). Ambos os métodos podem coexistir.

Configuração do Modo Agente

VariávelDescrição
CHATCLI_AGENT_ALLOW_SUDODefina como "true" para permitir que o agente sugira e execute comandos com sudo. Use com extrema cautela.
CHATCLI_AGENT_DENYLISTLista de padrões regex (separados por ;) para bloquear comandos adicionais no modo agente.
CHATCLI_AGENT_CMD_TIMEOUTTimeout para a execução de um único comando pelo agente (padrão: 10m, máximo: 1h).
CHATCLI_AGENT_PLUGIN_MAX_TURNSLimite máximo de turnos do agente no modo /agent//coder (padrão: 50, máximo: 200).
CHATCLI_AGENT_PLUGIN_TIMEOUTTimeout total do plugin do agente (padrão: 15m).

Multi-Agent (Orquestração Paralela)

VariávelDescriçãoPadrão
CHATCLI_AGENT_PARALLEL_MODEAtiva o modo multi-agent com orquestração paralela. O LLM orquestrador despacha agents especialistas em paralelo.false
CHATCLI_AGENT_MAX_WORKERSNúmero máximo de workers (goroutines) executando agents simultaneamente.4
CHATCLI_AGENT_WORKER_MAX_TURNSMáximo de turnos do mini ReAct loop de cada worker agent.10
CHATCLI_AGENT_WORKER_TIMEOUTTimeout por worker agent individual. Aceita durações Go (ex: 30s, 2m, 10m).5m

Para detalhes completos sobre o sistema multi-agent, consulte a documentação de Orquestração Multi-Agent.

Configuração do Modo Servidor (chatcli server)

VariávelDescriçãoPadrão
CHATCLI_SERVER_PORTPorta do servidor gRPC.50051
CHATCLI_SERVER_TOKENToken de autenticação para o servidor. Vazio = sem autenticação.""
CHATCLI_SERVER_TLS_CERTCaminho para o certificado TLS do servidor.""
CHATCLI_SERVER_TLS_KEYCaminho para a chave TLS do servidor.""
CHATCLI_GRPC_REFLECTIONHabilita gRPC reflection para debugging. Mantenha desabilitado em produção.false

Segurança e Controle

VariávelDescriçãoPadrão
CHATCLI_DISABLE_VERSION_CHECKDesabilita a verificação automática de versão no startup. Útil para ambientes air-gapped ou CI/CD.false
CHATCLI_GRPC_REFLECTIONHabilita gRPC server reflection (expõe schema do serviço).false

Para detalhes completos sobre segurança, consulte a documentação de Segurança e Hardening.

Configuração do Cliente Remoto (chatcli connect)

VariávelDescriçãoPadrão
CHATCLI_REMOTE_ADDREndereço do servidor remoto (host:port).""
CHATCLI_REMOTE_TOKENToken de autenticação para conectar ao servidor.""
CHATCLI_CLIENT_API_KEYSua própria API key/OAuth token, enviada ao servidor.""

Configuração do K8s Watcher (chatcli watch / chatcli server --watch-*)

VariávelDescriçãoPadrão
CHATCLI_WATCH_DEPLOYMENTNome do deployment Kubernetes a monitorar.""
CHATCLI_WATCH_NAMESPACENamespace do deployment."default"
CHATCLI_WATCH_INTERVALIntervalo entre coletas de dados. Aceita durações Go (ex: 10s, 1m)."30s"
CHATCLI_WATCH_WINDOWJanela temporal de dados mantidos em memória."2h"
CHATCLI_WATCH_MAX_LOG_LINESNúmero máximo de linhas de log coletadas por pod.100
CHATCLI_KUBECONFIGCaminho para o kubeconfig (opcional, usa default se não definido).Auto-detectado