Skip to main content
O ChatCLI suporta autenticação via OAuth 2.0 com PKCE e Device Flow (RFC 8628) para provedores que oferecem essas opções. Isso permite que você use seu plano existente (como ChatGPT Plus, Codex, Claude Pro ou GitHub Copilot) diretamente no terminal, sem precisar gerar ou colar chaves de API.

​
Métodos de Autenticação

Os dois métodos podem coexistir. O ChatCLI prioriza credenciais OAuth quando ambas estão disponíveis.
Suporte OAuth por provedor:
  • Com suporte a OAuth: OpenAI (ChatGPT Plus/Codex), Anthropic (Claude Pro) e GitHub Copilot (Device Flow).
  • Apenas chave de API: GoogleAI, xAI, ZAI, MiniMax, Moonshot (Kimi), StackSpot e Ollama. Para esses provedores, configure a chave via variável de ambiente no .env ou use /auth set.

​
Comandos /auth

Todos os comandos de autenticação possuem auto-completação — basta digitar /auth e pressionar Tab.

​
Ver Status

Exibe o status de autenticação de todos os provedores configurados, incluindo tipo de credencial (API Key vs OAuth), validade do token e origem.

​
Login via OAuth

1

Navegador abre automaticamente

O navegador abre na página de login do provedor.
2

Autorize o acesso

OpenAI: um servidor HTTP local captura o callback automaticamente (porta 1455).Anthropic: um servidor HTTP local em localhost:<porta-aleatória>/callback captura o código automaticamente. Após autorizar, o navegador é redirecionado para a página de sucesso oficial do Anthropic e o terminal completa o login. Se o servidor local não puder iniciar (porta indisponível, firewall) ou se CHATCLI_ANTHROPIC_LEGACY_OAUTH=1 estiver definido, o ChatCLI cai automaticamente no fluxo legado de copiar e colar o código.GitHub Copilot: insira o código do dispositivo exibido no terminal na página do GitHub.
3

Provedor disponível imediatamente

O provedor aparece imediatamente no /switch — sem reiniciar o app.

​
Provedores Suportados

​
Logout

Remove as credenciais OAuth armazenadas para o provedor específicado.

​
Detalhes Técnicos dos Fluxos OAuth

Esta seção descreve como cada fluxo OAuth funciona internamente, incluindo URLs, parâmetros e comportamento do ChatCLI.

​
Anthropic OAuth (PKCE + Callback Localhost, com fallback para paste)

O fluxo da Anthropic usa OAuth 2.0 com PKCE (Proof Key for Code Exchange) e um servidor HTTP local em localhost:<porta-aleatória>/callback para capturar o código de autorização — o mesmo padrão usado pelo Claude Code CLI. O fluxo legado de copiar e colar o código permanece disponível como fallback automático.

​
Fluxo primário (callback local)

1

Geração do PKCE e início do servidor local

O ChatCLI gera um code_verifier aleatório, calcula o code_challenge usando SHA-256 (método S256), e sobe um servidor HTTP em uma porta aleatória de localhost. Um state de 32 bytes (base64url, 43 caracteres) é gerado para proteção CSRF.
2

Abertura do navegador

O navegador abre na URL de autorização da Anthropic com code=true, o PKCE challenge, o state e o redirect_uri apontando para o servidor local.
3

Usuário autoriza no navegador

O usuário faz login no Claude e autoriza o acesso. O navegador é redirecionado para http://localhost:<porta>/callback?code=...&state=....
4

Validação CSRF e troca de tokens

O servidor local valida o state recebido contra o gerado, troca o código por tokens via platform.claude.com/v1/oauth/token e encerra o servidor. O navegador é redirecionado para a página de sucesso oficial do Anthropic (platform.claude.com/oauth/code/success).

​
Fluxo de fallback (copiar e colar)

Acionado automaticamente quando o servidor local não consegue se vincular à porta (firewall, porta em uso) ou quando CHATCLI_ANTHROPIC_LEGACY_OAUTH=1 é definido explicitamente.
1

Abertura do navegador no fluxo legado

O ChatCLI abre a URL de autorização legada (console.anthropic.com como redirect_uri).
2

Usuário copia o código

Após autorizar, a página do console exibe um código no formato código#state. O usuário cola o texto completo no terminal — o ChatCLI separa código e state automaticamente.
3

Troca do código por tokens

O ChatCLI envia código, state e code_verifier para o endpoint de tokens e recebe access_token + refresh_token.
Validações silenciosas do claude.ai — o fluxo primário só funciona se três parâmetros estiverem corretos. Caso contrário, a página de autorização retorna apenas “Invalid request format” sem código de erro:
  • code=true deve estar presente na query string
  • state deve ter exatamente 32 bytes (43 caracteres base64url) — state de 16 bytes é silenciosamente rejeitado
  • A URL de autorização deve ser claude.com/cai/oauth/authorize (faz 307 para claude.ai/oauth/authorize, e o redirect define cookies que a SPA precisa)
A troca e o refresh de tokens usam um http.Client puro (sem transporte customizado) com header User-Agent: claude-cli/2.1.2 (external, cli) para evitar fingerprinting TLS pelo Cloudflare. Usar um HTTP client com LoggingTransport causa rejeição pela CDN da Anthropic.
O refresh tenta primeiro platform.claude.com e cai automaticamente para console.anthropic.com/v1/oauth/token se o token tiver sido emitido pelo fluxo legado de paste.

​
OpenAI Codex OAuth (PKCE + Callback Localhost)

O fluxo da OpenAI usa OAuth 2.0 com PKCE e um servidor HTTP local para capturar o callback automaticamente.
1

Servidor local inicia na porta 1455

O ChatCLI inicia um servidor HTTP em http://localhost:1455 para receber o callback OAuth.
2

Navegador abre na página de autorização

O navegador abre na URL de autorização da OpenAI com o PKCE challenge e um parâmetro state para validação CSRF.
3

Usuário autoriza no navegador

Após login e autorização, o navegador redireciona para http://localhost:1455/auth/callback com o código de autorização.
4

Validação CSRF e troca de tokens

O servidor local válida o parâmetro state contra o valor gerado originalmente (proteção CSRF), troca o código por tokens e encerra o servidor.
O refresh de tokens é automático e utiliza o HTTP client padrão com logging.

​
GitHub Copilot Device Flow (RFC 8628)

O GitHub Copilot usa o Device Authorization Grant (RFC 8628), um fluxo projetado para dispositivos sem navegador integrado, como terminais CLI.
1

Requisição do device code

O ChatCLI solicita um device_code e um user_code ao endpoint do GitHub.
2

Exibição do código no terminal

O ChatCLI exibe o user_code e a URL de verificação (https://github.com/login/device) para o usuário.
3

Usuário autoriza no navegador

O usuário acessa a URL, insere o user_code e autoriza o acesso do ChatCLI.
4

Polling até autorização

O ChatCLI faz polling no endpoint de tokens a cada 5 segundos até receber o access token ou um erro terminal.
Respostas do polling:
Tokens do GitHub Copilot são não-expirantes e não possuem refresh token. São persistentes até revogação manual na página de configurações do GitHub.

​
Fluxo Completo: Do Zero ao Primeiro Prompt

Se você está começando sem nenhuma credencial configurada, siga estes passos:
1

Inicie o ChatCLI

Funciona mesmo sem credenciais configuradas.
2

Faça login via OAuth

3

Autorize no navegador

O navegador abre automaticamente na página de login do provedor.
4

Troque para o provedor

5

Envie seu primeiro prompt

​
Roteamento Automático de Endpoints (OpenAI)

O ChatCLI detecta automaticamente o tipo de credencial e roteia as requisições para o endpoint correto:
Você não precisa configurar nada — o roteamento é automático baseado no tipo de token.
No backend Codex, o ChatCLI também envia os headers de identificação de cliente que o backend exige (originator mais um User-Agent do Codex). Slugs de modelos mais novos — como a família GPT-5.6 (gpt-5.6-sol, gpt-5.6-terra, gpt-5.6-luna) — só são servidos quando os dois headers estão presentes; sem eles o backend responde 404 Model not found (o Luna, por exemplo, não tem fallback do lado do servidor).

​
Armazenamento de Credenciais

As credenciais OAuth são salvas com criptografia AES-256-GCM em:

​
Detalhes de Criptografia

A chave de criptografia é gerada automaticamente e armazenada em ~/.chatcli/.auth-key. Dados não-criptografados de versões anteriores são detectados automaticamente (ausência do prefixo chatcli-enc:v1:) e migrados para o formato criptografado na próxima gravação. Cada perfil armazenado contém:
  • Access token (criptografado)
  • Refresh token (criptografado, quando aplicável)
  • Expiry (timestamp em milissegundos)
  • Account ID e email do provedor
  • Tipo de provedor (anthropic, openai-codex, github-copilot)
Para personalizar o diretório de armazenamento, defina a variável de ambiente:

​
Validação de Tokens

O ChatCLI implementa validação rigorosa de tokens OAuth para prevenir uso de credenciais inválidas ou expiradas:

​
Validação de Access Token

  • Rejeição de tokens vazios — Tokens com access token vazio são rejeitados imediatamente, sem tentar fazer requests. Isso previne erros confusos de “unauthorized” quando as credenciais estão corrompidas.
  • Validação de expiração — O campo expiry é verificado antes de cada request. Tokens expirados disparam o fluxo de refresh automaticamente.

​
Tempo de Vida Máximo de Token (CHATCLI_MAX_TOKEN_LIFETIME)

Para ambientes de produção com requisitos de conformidade, você pode limitar o tempo de vida máximo de tokens:
Quando o tempo de vida máximo é atingido, o token é invalidado e o usuário precisa fazer login novamente via /auth login. Isso garante rotação periódica de credenciais mesmo quando o refresh token ainda é válido.

​
Renovação Automática de Tokens

O ChatCLI renova tokens expirados automaticamente em duas camadas:

Renovação Proativa

Ao resolver credenciais para um request, o ChatCLI verifica se o token está expirado (IsExpired()) ou prestes a expirar (IsExpiringSoon() com margem de 5 minutos). Se sim, o refresh é executado antes do request.

Renovação Reativa

Se um request retornar erro HTTP 401, o ChatCLI invalida o cache de credenciais, executa o refresh do token, recria o cliente HTTP e retenta o request automaticamente — tudo transparente para o usuário.
A margem de segurança de 5 minutos antes da expiração real evita race conditions em que o token expira entre a verificação e o envio do request.
Tokens do GitHub Copilot (Device Flow) não expiram e não possuem refresh token — são persistentes até revogação manual.

​
Sincronização com CLIs Externos

O ChatCLI pode importar credenciais de CLIs externos via SyncExternalCliCreds():
A importação só ocorre se as credenciais externas forem mais recentes que as já armazenadas. Isso garante que um login feito diretamente no ChatCLI não seja sobrescrito por dados antigos de outro CLI.

​
Prioridade de Resolução de Credenciais

Ao determinar qual credencial usar para um provedor, o ChatCLI segue está ordem de prioridade:
1

Auth-profiles store (OAuth/Token)

Credenciais OAuth armazenadas em auth-profiles.json, incluindo perfis sincronizados de CLIs externos. O refresh automático é aplicado nesta camada.
2

Variáveis de ambiente

Variáveis como ANTHROPIC_OAUTH_TOKEN, ANTHROPIC_API_KEY, OPENAI_API_KEY e GITHUB_COPILOT_TOKEN.
Sistema de prefixos: o valor das credenciais pode incluir prefixos que indicam o tipo ao provedor:

​
Configuração Avançada

​
Solução de Problemas

O fluxo primário usa um servidor HTTP local em localhost:<porta-aleatória>/callback. Se sua porta estiver bloqueada por firewall ou se você estiver em um ambiente sem localhost acessível (containers, sessões SSH sem port-forward), force o fluxo legado de paste:
No fluxo legado, o navegador abre na página do console que exibe o código no formato código#state. Copie o texto completo (incluindo a parte após o #) e cole no terminal — o ChatCLI separa código e state automaticamente.
O claude.ai valida silenciosamente três parâmetros do fluxo primário e retorna apenas “Invalid request format” se algum estiver errado:
  • code=true ausente na query string
  • state com tamanho diferente de 32 bytes (43 caracteres base64url)
  • URL de autorização diferente de claude.com/cai/oauth/authorize
Se você modificou o código da função loginAnthropicLocalhost, verifique esses três pontos antes de qualquer outra coisa.
Isso geralmente ocorre quando um HTTP client customizado (com LoggingTransport) é usado. O ChatCLI usa um http.Client puro para a troca de tokens da Anthropic, evitando fingerprinting TLS pelo Cloudflare. Se você estiver desenvolvendo, certifique-se de que a função exchangeAnthropicToken usa um client sem transporte customizado.
Execute /auth status para verificar se o token foi salvo corretamente. Se necessário, tente /auth logout <provedor> seguido de /auth login <provedor>.
Certifique-se de que sua conta GitHub possui uma assinatura ativa do Copilot (Individual, Business ou Enterprise). Verifique em https://github.com/settings/copilot se o Copilot está habilitado.
O device code tem validade limitada. Se o polling exceder 15 minutos sem autorização, o código expira. Execute /auth login github-copilot novamente para gerar um novo código.
Os tokens OAuth são renovados automaticamente de duas formas:
  • Proativamente: ao resolver credenciais, se o token estiver expirado ou dentro da margem de 5 minutos, o refresh é tentado antes do request.
  • Reativamente: se um request retornar erro 401, o ChatCLI invalida o cache de credenciais, tenta renovar o token OAuth, recria o cliente e retenta o request automaticamente.
Se ambas as tentativas falharem (ex: refresh token também expirado), faça login novamente com /auth login.Tokens do GitHub Copilot (Device Flow) não expiram e não possuem refresh token — são persistentes até revogação manual.

​
Próximos Passos

Referência de Comandos

Lista completa de todos os comandos disponíveis.

Configuração (.env)

Todas as variáveis de ambiente disponíveis.

Uso Básico

Aprenda os fundamentos do ChatCLI.