Os 4 métodos de autenticação CLI que importam, como GitHub, AWS e ferramentas de IA os implementam, e os erros de segurança que você vai querer evitar.
Todo CLI de desenvolvedor vem com login como seu primeiro comando. E cada um resolve a autenticação de maneira diferente.
O GitHub mostra um código e abre seu navegador para você verificá-lo. A AWS abre um navegador para SSO baseado em PKCE. O Stripe faz você confirmar um código de emparelhamento no painel de controle. As ferramentas de IA mais recentes (Claude Code, OpenAI Codex CLI, Cursor) também escolheram suas próprias abordagens.
Se você está construindo um CLI, a autenticação é uma das primeiras coisas que você precisa definir. Escolha o método errado e você ouvirá sobre isso: usuários frustrados, auditorias de segurança ou ambos. E com a recente onda de agentes de codificação de IA que chamam ferramentas CLI programaticamente, os riscos aumentam: você não está mais autenticando apenas um humano. Você pode estar entregando credenciais para um processo autônomo.
Aqui estão os quatro métodos de autenticação que importam, como as maiores ferramentas os implementam e os erros que você vai querer evitar.
Antes de aprofundar, aqui está uma comparação rápida:
| Método | Melhor para | Segurança | Precisa de navegador? |
|---|---|---|---|
| OAuth Device Code Flow | Ambientes headless, SSH | Alta | Não (na mesma máquina) |
| OAuth baseado em navegador (redirect localhost) | Desenvolvimento local | Máxima | Sim |
| API Keys / PATs | Automação, CI/CD, prototipagem rápida | Moderada | Não |
| Client Credentials | Máquina-a-máquina, serviços | Alta | Não |
Cada um tem pontos positivos e negativos. Aqui está o que você precisa saber sobre cada um.
Esse é aquele onde seu CLI mostra um código como ABCD-1234 e uma URL, então pede para você abrir a URL em qualquer dispositivo e digitar o código.
Quem usa: GitHub CLI (padrão), Azure CLI (via --use-device-code), Vercel CLI (recentemente mudou para este como padrão), OpenAI Codex CLI (como opção beta)
cli loginclient_id e scopes solicitadosdevice_code (identificador interno), um user_code (o código curto que você digita) e um verification_uri (para onde ir)O grande diferencial: funciona em qualquer lugar. Sessão SSH em um servidor remoto? Funciona. Rodando dentro de um container Docker? Funciona. IDE na nuvem sem navegador local? Funciona. O navegador não precisa estar na mesma máquina do CLI.
Também suporta toda a gama de autenticações corporativas (SAML, OIDC, MFA), porque tudo isso ocorre no navegador, não no terminal. O CLI nunca vê sua senha.
Device code flow tem um problema de phishing. Um atacante pode iniciar um pedido de device code, obter um user code legítimo e enganar você para digitar, autorizando efetivamente a sessão do atacante. Isso não é teórico. Pesquisadores já documentaram esse ataque contra a autenticação por device code do AWS SSO.
Isso é preocupante o suficiente para que a AWS mudou o padrão. A partir do AWS CLI v2.22.0, o padrão para aws sso login mudou do device code flow para autorização baseada em PKCE. Device code ainda está disponível via --use-device-code, mas não é mais o caminho padrão.
Enquanto isso, o próprio tenant da Microsoft começou a bloquear totalmente o device code flow via políticas de acesso condicional — um forte sinal de que consideram este método de alto risco.
Então temos um cenário curioso: Vercel adotou device code flow como padrão em setembro de 2025, enquanto a AWS se afastou. O padrão parece ser: device code flow é ótimo para ambientes onde você realmente não consegue abrir um navegador, mas se é possível abrir localmente, PKCE é mais seguro.
Do lado dos provedores de autenticação, a demanda está crescendo. Logto acabou de lançar suporte ao OAuth 2.0 Device Authorization Grant para apps nativos na v1.38.0 (open source) e Logto Cloud, então você já pode habilitar device flow como método de autorização para qualquer app nativo. Isso importa se você constrói um CLI. Implementar corretamente o RFC 8628 (expiração do código, rate limit, polling, UX da página de verificação) dá mais trabalho do que parece, e deixar o provedor cuidar disso significa só fazer as chamadas HTTP certas.
Alguns pontos do RFC 8628:
expires_in é definido pelo servidor de autenticação. O RFC usa 1800 segundos (30 minutos) como exemplo, mas não é uma exigência fixa.interval), clientes devem usar 5 segundos por padrão.slow_down exige adicionar 5 segundos ao intervalo.Este é o método mais comum para CLIs rodando na máquina local do desenvolvedor. Você executa login, seu navegador abre, você autentica, e o navegador redireciona para um servidor local temporário criado pelo CLI. Implementações modernas usam PKCE (pronuncia-se "pixie"), que torna o fluxo bem mais seguro.
Quem usa: Claude Code, gcloud CLI, Terraform CLI, AWS CLI v2.22+ (para SSO, com PKCE como padrão)
cli loginhttp://127.0.0.1:8742)http://127.0.0.1:8742/callback?code=XXXX&state=YYYYA experiência do usuário é suave. Sem copiar códigos, sem digitar URLs. Apenas uma aba do navegador que abre e fecha.
Isso só funciona quando o CLI pode abrir um navegador e escutar no localhost. Isso exclui:
Por isso a maioria das ferramentas que usam OAuth pelo navegador também tem um fallback, normalmente device code flow ou API keys.
Erro 1: Bind no 0.0.0.0 ao invés de 127.0.0.1
Esse é o erro mais frequente, e é grave. Se seu servidor de callback escuta em todas as interfaces, qualquer um na rede pode interceptar o código de autorização.
Já vi isso em CLIs de produção. Muitos frameworks de servidor HTTP usam 0.0.0.0 por padrão.
Erro 2: Falta de validação do parâmetro state
O parâmetro state é sua proteção contra CSRF. Sem ele, um atacante pode enganar seu CLI para aceitar um código de autorização de uma sessão maliciosa.
Erro 3: Não usar PKCE
Se seu fluxo OAuth não usa PKCE (Proof Key for Code Exchange), o código de autorização pode ser interceptado e reutilizado.
No fluxo padrão de authorization code, se um atacante intercepta o código (pela rede ou lendo a URL de redirect), pode trocar por tokens. PKCE impede isso exigindo prova de que quem troca o token é o mesmo que iniciou a autorização.
O que PKCE adiciona ao fluxo:
code_verifier aleatório (string de alta entropia)code_challenge aplicando hash SHA-256code_verifierUm atacante sem o code_verifier não conclui a troca.
Por isso o AWS CLI v2.22+ tornou PKCE padrão para SSO, deixando o device code flow para quem não pode abrir navegador local. Quando um browser está disponível na mesma máquina, OAuth com PKCE é melhor: mesma UX, segurança maior, sem vetor de phishing. Device code flow ainda serve para quando o navegador não pode estar na mesma máquina (SSH, containers, dev remoto), mas não é o caso comum do desenvolvimento local.
A abordagem mais simples. Você gera um token no painel web, cola na config do CLI ou numa variável de ambiente, e pronto.
Quem usa: Stripe CLI (como opção de login), npm, pip, maioria das ferramentas de IA como fallback (Claude Code via ANTHROPIC_API_KEY, OpenAI via OPENAI_API_KEY, Aider)
sk_live_, ghp_, npm_)~/.config/stripe/config.toml, ~/.aws/credentials) ou variável de ambienteO CLI lê na inicialização e usa em requisições API, como um token Bearer no header Authorization.
Para automação, API keys são imbatíveis. Funcionam em CI/CD, containers, scripts, cron jobs. Qualquer lugar que leia variável de ambiente. Não precisa de navegador. Sem prompts interativos. Sem necessidade de refresh de token.
Para fluxos com agentes de IA, API key é o caminho mais fácil. O Claude Code ou Cursor precisam chamar uma API — basta uma variável de ambiente com API key.
A jogada inteligente ao usar API keys: troque por tokens de curta duração em tempo de execução.
A AWS popularizou isso com STS (Security Token Service). Suas credenciais longas só servem para pedir credenciais temporárias válidas por 1h. Ferramentas como aws-vault automatizam tudo.
Mesmo começando com API keys, considere adicionar esse padrão. Ele reduz a janela de dano de "até alguém perceber" para "uma hora".
Esse fluxo OAuth 2.0 é para autenticação máquina-máquina: serviços conversando entre si, sem humanos envolvidos.
Usado em: CI/CD pipelines, serviços de background, automações
O serviço envia client_id e client_secret direto para o servidor de autenticação e recebe um access token temporário. Sem navegador, sem interação, sem redirecionamento.
Use client credentials quando:
Não use para autenticação de humanos. Não suporta MFA, SSO nem verificação interativa.
Aqui está um resumo correto baseado na documentação e código fonte atuais. Muitos artigos erram porque as ferramentas mudam o padrão com frequência.
| Ferramenta CLI | Autenticação padrão | Alternativas | Armazenamento de token |
|---|---|---|---|
GitHub CLI (gh) | Device code flow via navegador | PAT (--with-token), env var (GH_TOKEN) | Chaveiro do SO (fallback: arquivo texto) |
| AWS CLI v2 | Fluxo auth code PKCE (SSO) | Device code (--use-device-code), credential files | ~/.aws/sso/cache/ |
Azure CLI (az) | WAM no Windows; auth code no Linux/macOS | Device code (--use-device-code) | ~/.azure/msal_token_cache.* |
| Vercel CLI | Device code flow (novo padrão, set/2025) | API token (--token, env var) | ~/.local/share/com.vercel.cli/auth.json |
| Stripe CLI | Fluxo de emparelhamento via navegador | API key (--interactive, --api-key, env var) | ~/.config/stripe/config.toml |
| gcloud CLI | OAuth pelo navegador | --no-browser manual flow | ~/.config/gcloud/ |
| Claude Code | OAuth navegador | API key (env var, apiKeyHelper) | Chaveiro SO / ~/.claude/.credentials.json |
| OpenAI Codex CLI | OAuth navegador | Device code (beta), API key | ~/.codex/auth.json / Chaveiro SO |
| Terraform CLI | OAuth navegador | Token paste | ~/.terraform.d/credentials.tfrc.json |
A tendência é clara: OAuth navegador é padrão para dev local, device code flow é fallback para headless, API keys para automação. PKCE cresce como opção mais segura quando navegador está disponível.
Fazer a autenticação certa de nada adianta se guardar o token errado.
Todo SO tem um cofre de credenciais embutido e criptografado:
Eles fornecem criptografia, controle de acesso e integração com hardware. Seu CLI não precisa implementar cripto por conta própria.
Quando não dá para usar chaveiro (containers, Linux minimalista), use arquivos criptografados e permissões restritas:
Arquivos texto puro. Parece óbvio, mas há ferramentas que ainda fazem isso. Um arquivo texto com token pode ser lido por qualquer processo do seu usuário, ferramenta de backup, ou alguém com acesso temporário à máquina.
Variáveis de ambiente para armazenamento longo. Variáveis de ambiente aparecem em listagens de processos, logs de crash, e são herdadas por processos filhos. Ótimas para CI/CD (onde a plataforma protege o segredo), mas arriscadas para desenvolvimento local.
Browser localStorage. Se seu CLI possui componente web, não guarde tokens em localStorage. Um XSS expõe tudo.
Devem ser de curta duração. Uma hora é padrão. Quando expira, o CLI faz refresh automaticamente. O usuário não precisa fazer login de novo em operações comuns.
Refresh tokens são credenciais de longa duração que permitem conseguir novos tokens sem reautenticar. São alvos valiosos por durarem dias ou meses.
Sistemas modernos rotacionam o refresh token a cada uso:
Assim, se o refresh token for roubado, ao tentar usar ele após o legítimo, o servidor detecta o reuso e invalida toda a família do token. O token do invasor e do usuário legítimo param de funcionar, forçando novo login, mas bloqueando o atacante de manter acesso.
Já falado acima, mas vale repetir: sempre use 127.0.0.1, nunca 0.0.0.0.
Isso acontece mais do que se admite. Um log de debug, handler de erro que despeja headers, modo verbose que imprime tudo.
Imagens Docker não são cofres. Cada layer é extraível.
Se um token expirar no meio da operação, não falhe com erro 401. Tente um refresh, só peça login se o refresh também expirou.
Não peça scope admin:* quando só precisa de repo:read. Vale para OAuth scopes e permissões de API key.
Quando um agente de IA usa seu CLI, isso é crucial. Você provavelmente não quer o assistente IA com permissão de deletar-repositório só para ler código.
O que faz 2026 ser diferente de 2023: CLIs não são só para humanos digitando comandos. Agentes de IA como Claude Code, Codex e Cursor (modo agent) chamam CLIs programaticamente. Isso cria novos desafios:
Permissões delegadas. Quando Claude Code faz gh pr create, usa suas credenciais do GitHub. Mas será que o agente deve ter os mesmos privilégios que você? O princípio de menor privilégio diz que não, mas quase nenhuma ferramenta permite restringir as permissões do agente.
Exposição de credenciais. Se sua API key está na env var, todo processo pode ler, inclusive o subprocesso do agente. Ferramentas como Claude Code mitigam com scripts apiKeyHelper que geram tokens temporários sob demanda, mas não é universal ainda.
Autenticação headless para agentes. Um agente de IA sandboxed não pode abrir navegador. Device code flow funciona (humano aprova em outro dispositivo), mas API keys ainda são a solução mais comum pois não exigem interação.
Trilhas de auditoria. Quando o agente faz chamadas API com suas credenciais, o log mostra você fez. Não existe hoje um padrão para separar "o humano fez" de "o agente fez em nome do humano".
Esse campo evolui rápido. O que fazer agora:
Precisa escolher um método?
"Meus usuários são desenvolvedores em máquinas locais" → OAuth navegador com PKCE (máxima segurança + UX suave)
"Meu CLI precisa rodar via SSH e containers" → Device code flow como fallback, OAuth navegador como primário
"Roda em CI/CD sem humano" → Client credentials flow ou API keys restritos
"Quero implementar rápido" → API keys (mas adicione rotação depois)
"Clientes enterprise precisam de SSO e MFA" → Qualquer fluxo OAuth (device code ou navegador), suporta tudo corporativo
"Agentes de IA vão usar este CLI" → Suporte API keys (para integração fácil de agente) + OAuth navegador (para humanos), com permissões restritas e tokens de curta duração
É seguro contra a maioria dos ataques, mas tem vulnerabilidade de phishing conhecida. Um atacante pode criar device code e enganar o usuário para autorizar. Por isso a AWS adotou PKCE como padrão no SSO login. Para ambientes headless onde PKCE não é viável, device code flow ainda é a melhor opção. Apenas fique atento ao risco de phishing.
Em CI/CD: sim — a plataforma cifra elas em disco e injeta só na execução. Para desenvolvimento local: não. Use o chaveiro do SO. Variáveis de ambiente aparecem em listagens de processos, logs, e são herdadas pelos filhos.
Na prática, pouca. Ambos são credenciais longas para autenticar APIs. O uso é principalmente organizacional: API keys normalmente valem para apps/projetos, personal access tokens são atrelados à conta de usuário. Alguns serviços usam termos de modo intercambiável.
Access tokens: a cada hora ou menos (o refresh é automático). Refresh tokens: rode a rotação a cada uso (via servidor). API keys: no mínimo a cada 90 dias, ou imediatamente ao suspeitar de vazamento. Na prática, times só rotacionam API key após incidente — o que é tarde demais.
Três opções, na ordem de prioridade:
docker run -e API_KEY=${API_KEY}) em CI/CDdocker run -v ~/.config/tool:/root/.config/tool:ro) no dev localNunca coloque credenciais na imagem. Nunca.
MCP é o padrão emergente para agentes de IA conectarem com ferramentas externas. Traz uma nova dimensão: o agente precisa de credenciais para o servidor MCP, que por sua vez precisa de credencial para APIs downstream. Isso está em padronização. No momento, MCP usa API key ou OAuth passado na config. Isso pode evoluir rápido.
A autenticação CLI está mudando rápido. O que era boa prática dois anos atrás (device code flow como padrão, arquivos de credencial texto) já está sendo substituído. Se vai adicionar autenticação a um CLI hoje, comece com OAuth navegador + PKCE para humanos, API keys para automação, e pense no dia em que agentes de IA serão seus principais usuários.