Duas contas Cloudflare, um terminal: Wrangler sem logout

O problema

Eu fazia o deploy (que é o processo de publicar um site na internet) do meu portfólio usando o Wrangler — que é a CLI (uma ferramenta de linha de comando, onde digitamos instruções em texto) da Cloudflare. Eu estava logado na minha conta pessoal através do OAuth (aquele login tradicional que abre a página do navegador para você autorizar o acesso). Até aí, tudo funcionava bem.

O problema começou quando um cliente me pediu para publicar um sistema direto na conta dele.

A partir daí, começou um ritual chato: eu tinha que rodar o comando wrangler logout, depois wrangler login de novo, abrir o navegador, logar na conta do cliente e só então fazer o deploy. No dia seguinte, eu tinha que refazer todo esse caminho inverso para conseguir voltar para a minha conta pessoal.

Para piorar, essas sessões de login no navegador às vezes se misturam. Com isso, o deploy podia ir parar na conta errada sem eu perceber — e eu só descobria quando o cliente me avisava que o projeto não tinha aparecido na conta dele.

Eu já estava quase aceitando essa chateação como o “preço de ter vários clientes”, até descobrir que o Wrangler tem uma forma muito mais inteligente e limpa de resolver isso: o isolamento por variável de ambiente (que são como “etiquetas de informação” temporárias que você passa para o terminal).

A solução real não é tentar “gerenciar os logins melhor”. É simplesmente não usar o login tradicional para isso.

Por que CLOUDFLARE_API_TOKEN resolve

O Wrangler foi projetado para dar prioridade às variáveis de ambiente em vez do login via navegador (OAuth global), que fica salvo no seu computador no caminho ~/.config/.wrangler.

Se uma variável chamada CLOUDFLARE_API_TOKEN estiver presente no terminal no momento em que você executa um comando, o Wrangler ignora o usuário que está logado no navegador e funciona exclusivamente na conta à qual aquele token pertence.

Pense no token como um crachá de visitante com permissões específicas. Isso significa que você pode manter seu login normal via navegador para a sua conta pessoal (o que é prático no dia a dia) e usar esses crachás virtuais (tokens) no terminal para as contas dos clientes. Assim, você isola os acessos sem precisar dar logout nunca.

O processo, na ordem que executei

1. Gerar o token na conta do cliente

Peça ao cliente (ou acesse junto com ele) o painel da Cloudflare. Vá no menu em Profile → API Tokens → Create Token. Escolha um modelo pronto adequado (Edit Cloudflare Workers para o serviço de Workers, ou um modelo personalizado para o Pages). Defina apenas as permissões mínimas necessárias — ou seja, estritamente o que o deploy precisa para funcionar. Isso vai gerar uma sequência longa de letras e números. Guarde essa chave com muito cuidado.

Princípio do menor privilégio: nunca crie um token com acesso total (do tipo “Account: Everything”). Crie apenas com as permissões que o projeto realmente precisa (Workers Scripts: Edit, Pages: Edit). Se essa chave vazar por acidente, o estrago será limitado.

2. Especificar o account_id no wrangler.toml

O Wrangler precisa saber exatamente em qual conta deve operar. No arquivo de configuração do projeto do cliente, o wrangler.toml, adicione o identificador da conta:

name = "projeto-do-cliente"
account_id = "identificador_da_conta_cliente"

Sem esse ID de conta, mesmo que você esteja usando o token correto, o Wrangler pode se confundir entre as contas.

3. Deploy com a variável inline

Em vez de salvar a variável no sistema inteiro (o que sujaria toda a sua sessão de terminal), passe a variável inline — ou seja, diretamente na mesma linha do comando de deploy, funcionando apenas para aquela execução específica:

CLOUDFLARE_API_TOKEN="cole_o_token_do_cliente_aqui" npx wrangler deploy

O comando roda na conta do cliente usando as permissões exatas daquele token. Assim que a execução termina, o terminal volta ao estado normal. Se você rodar npx wrangler pages list logo no minuto seguinte, o terminal vai listar os projetos da sua conta pessoal — porque aquela chave temporária que você usou na linha de cima já deixou de existir.

O que eu fiz pra não decorar token

Como o token é um segredo, ele não deve ir para atalhos públicos do sistema como os aliases ou para o seu arquivo .bashrc. Por outro lado, ficar copiando e colando a chave a cada deploy é algo muito chato.

A solução que adotei foi criar um arquivo chamado .env.cloudflare para cada projeto (ficando salvo dentro da pasta do cliente, protegido com o comando chmod 600 para que apenas o meu usuário do sistema consiga ler, e adicionado ao .gitignore para nunca ser enviado para repositórios públicos):

# projeto-do-cliente/.env.cloudflare (chmod 600, .gitignore)
export CLOUDFLARE_API_TOKEN="cole_o_token_aqui"
export CLOUDFLARE_ACCOUNT_ID="identificador_da_conta"

No arquivo wrangler.toml de cada projeto, eu mantenho o account_id apontado para a conta correta. Na hora de fazer o deploy, eu só preciso carregar as variáveis desse arquivo local:

set -a; . .env.cloudflare; set +a
npx wrangler deploy

O isolamento fica perfeito. Cada projeto “sabe” em qual conta deve mexer, e eu não preciso memorizar nenhum código. Além disso, o login da minha conta pessoal continua funcionando perfeitamente para quando eu voltar a mexer no meu portfólio.

A armadilha que evitei

A grande tentação aqui é salvar o CLOUDFLARE_API_TOKEN no arquivo .bashrc global do seu computador. Não faça isso. Se você fizer, todos os comandos do Wrangler passarão a usar aquele token — inclusive os comandos da sua conta pessoal, que agora vão tentar rodar com as permissões limitadas do token em vez do seu login completo. Isso quebra as coisas de forma silenciosa: comandos que funcionavam antes param de funcionar sem mostrar uma mensagem de erro clara.

A regra que defini para mim foi: variável de ambiente para token é sempre usada inline ou em arquivo .env próprio do projeto, nunca de forma global. Um token global vira uma configuração permanente que você esquece que existe — e é justamente no que a gente esquece que os bugs mais difíceis aparecem.

O que aprendi

A grande lição técnica deste caso é: separar os acessos por contexto (escopo) é muito mais seguro do que confiar na sua própria memória. Eu confiava no login do navegador porque “achava que lembrava” em qual conta estava logado — só que a nossa memória falha, principalmente quando alternamos entre vários projetos no mesmo dia. Com os tokens definidos por projeto, a separação fica automática: você não corre o risco de errar porque o próprio ambiente te direciona para a conta certa.

E o segundo aprendizado, mais geral para quem trabalha com TI: toda ferramenta que suporta múltiplas contas tem um mecanismo para separar esses acessos — basta descobrir qual é. O Wrangler usa a variável de ambiente. O Git usa o recurso includeIf por diretório. O SSH usa blocos de Host no seu arquivo de configuração. Quem tenta gerenciar várias identidades “de cabeça” está fazendo manualmente o que a ferramenta já sabe fazer de forma automática. Vale muito a pena gastar 20 minutos lendo a documentação de “múltiplas contas” das ferramentas que você usa no dia a dia.

Leia também

• DNS no Cloudflare: nuvem laranja vs cinza e quando usar cada
• Cloudflare Workers + D1: o padrão que adotei pra APIs no edge
• Engenharia reversa de um projeto Cloudflare: por onde começar