Quando eu usava o Wrangler numa tarefa longa, às vezes o terminal parava para pedir que eu aprovasse um login no navegador. Se eu estava trabalhando com uma IA, ela ficava esperando a minha confirmação. Um API Token resolve esse tipo de interrupção: o Wrangler pode autenticar pelos valores definidos no ambiente, sem abrir uma sessão interativa a cada comando.
Use token quando o terminal precisa continuar sem você
Wrangler é a ferramenta de linha de comando oficial da Cloudflare. O login pelo navegador funciona bem para uso manual; o token é útil quando você automatiza tarefas, publica por um processo que não pode esperar por uma janela ou trabalha com um agente que executa comandos. A mesma ideia existe em outros serviços, mas cada CLI define o nome da sua variável e o tipo de credencial que aceita.
Uma variável de ambiente guarda a configuração fora do código do site. Isso não faz dela um cofre: qualquer processo que receba aquele valor pode usá-lo. Trate o token como uma senha, evite incluí-lo no repositório e mantenha as permissões limitadas ao que os comandos realmente precisam.
Crie um token com acesso apenas às tarefas necessárias
No painel da Cloudflare, abra a área de API Tokens e crie um token. Escolha a opção adequada à forma como você administra a conta, depois conceda acesso somente aos recursos que o Wrangler vai alterar. Para publicar Workers, comece pelo modelo de token voltado a Workers e confira quais produtos ele habilita. Se também precisa alterar DNS, adicione a permissão de edição de DNS para a zona específica; não é necessário liberar todas as zonas da conta.
Você pode restringir o token ao seu endereço de IP se ele não muda e definir uma data de validade. Eu deixei o meu sem vencimento por conveniência no computador que uso para trabalhar, mas não trataria isso como a configuração mais segura para todo mundo. Uma validade menor e permissões mais estreitas reduzem o estrago possível se a chave vazar. A Cloudflare mostra o segredo uma vez: copie-o para o local protegido que escolheu e não o cole em código, mensagem ou arquivo versionado.
Configure as duas variáveis reconhecidas pelo Wrangler
As variáveis são `CLOUDFLARE_API_TOKEN` e `CLOUDFLARE_ACCOUNT_ID`. O Account ID aparece nos detalhes da conta no painel; confira o identificador antes de salvá-lo e não o confunda com o Zone ID do domínio.
No Mac ou Linux, você pode exportar os valores no shell. No zsh, as linhas são `export CLOUDFLARE_API_TOKEN="seu-token"` e `export CLOUDFLARE_ACCOUNT_ID="id-da-conta"`. Para carregar os valores nos terminais seguintes, coloque-os na configuração do seu shell, como `~/.zshrc`; no Bash, use o arquivo correspondente. Se precisar deles em um único projeto, a documentação atual também aceita um `.env` na pasta do projeto. Deixe esse arquivo fora do Git e confira que a aplicação não esteja expondo o conteúdo como dado público.
No Windows, crie as duas variáveis nas configurações de Ambiente do usuário ou configure-as pelo PowerShell ou pelo CMD. Depois de salvar, abra um terminal novo para o processo ler os valores. Os nomes antigos `CF_API_TOKEN` e `CF_ACCOUNT_ID` foram substituídos pelos nomes completos; use as variáveis atuais para evitar mensagens de depreciação.
Confira a conta antes de continuar com o Wrangler
Em um terminal novo, rode `npx wrangler whoami`. O comando não publica nada: ele mostra a identidade e a conta reconhecidas pelo Wrangler. Na minha execução, também informou que estava usando o token definido em `CLOUDFLARE_API_TOKEN` e encontrou o Account ID.
Se o comando falhar, confira a grafia das variáveis, abra outro terminal e confirme as permissões do token para a operação que você pretende fazer. O Wrangler atual prioriza `CLOUDFLARE_API_TOKEN` quando ela está definida, mesmo que você tenha feito `wrangler login` naquela máquina. Se trabalha com várias contas, olhe a saída do `whoami` antes de publicar para saber qual credencial está ativa.
Depois desse teste, os próximos comandos podem rodar sem esperar que você clique numa aprovação no navegador. Se você só usa o terminal manualmente e o login já funciona para o seu fluxo, não precisa criar outro token sem uma razão. Para automação, use uma credencial própria, guarde-a fora do código e dê a ela apenas os acessos que a tarefa pede.