Cloudflare CLI na prática: instalação, comandos e migração

O ganho prático não está em encurtar um comando, mas em reduzir o trabalho de integração. Quem está à frente de uma startup consegue inspecionar uma conta sem vasculhar o painel; uma equipe de plataforma pode entregar resultados legíveis por máquina a um agente; e uma agência pode padronizar o trabalho com a Cloudflare entre contas de clientes sem manter um wrapper de API separado para cada produto.

Não há uma licença separada do cf para comprar. O repositório é open source, um Worker pequeno pode começar no plano Free da Cloudflare e o Workers Paid tem cobrança mínima mensal de $5. Na outra ponta do orçamento, uma plataforma geral de governança de infraestrutura como a Spacelift lista um plano Starter+ de $20,000. O cf elimina boa parte do encanamento de API entre esses extremos. Ele não elimina a necessidade de aprovações, trilhas de auditoria nem permissões criteriosas.

Cloudflare CLI: como funciona o novo cf na prática

O cf oferece uma superfície de comandos gerada para toda a API da Cloudflare, além de fluxos de projeto construídos manualmente para tarefas como criar, compilar, migrar e implantar Workers. Pense no Wrangler como uma bancada especializada e bem equipada para Workers. O cf acrescenta o diretório e o balcão de atendimento para todo o edifício da Cloudflare, mas ainda encaminha alguns trabalhos de Worker ao Wrangler quando ele continua sendo a ferramenta mais confiável.

Essa diferença também separa este lançamento da prévia técnica apresentada pela Cloudflare em 13 de abril. A versão de abril cobria apenas uma pequena parte dos produtos. Já o open beta de setembro traz cobertura completa da API, respostas JSON por padrão, busca de comandos, configuração de Workers em TypeScript e Vite como caminho padrão para Workers.

Os quatro componentes que mudam o fluxo são diretos:

• Cobertura completa da API: os comandos gerados seguem cf <product> [group…] <operation> em mais de 3,000 operações.
• Busca de comandos: cf cli search recebe uma tarefa em linguagem natural e devolve cinco correspondências em JSON, ordenadas por relevância. Não é preciso decorar a árvore de comandos.
• JSON por padrão: os resultados estruturados da API chegam à saída padrão como JSON formatado, permitindo que uma pessoa, um script ou um agente de programação filtre a mesma resposta.
• Configuração tipada de Worker: cloudflare.config.ts oferece feedback de TypeScript a editores e agentes de programação. Hoje, isso começa pelos Workers. Configurar DNS, zonas e políticas de uma conta inteira é uma direção futura, não uma funcionalidade atual.

Como instalar e autenticar o Cloudflare CLI com uma consulta segura

Comece com uma operação somente leitura. Assim você confirma pacote, credencial, seleção de conta, descoberta de comandos e o caminho dos dados em JSON antes de permitir que um script altere qualquer coisa.

O pacote oficial exige Node.js 22 ou mais recente. Para quem trabalha no terminal, cf auth login gerencia o perfil OAuth padrão. Em CI, defina um CLOUDFLARE_API_TOKEN com escopo restrito; o cf verifica essa variável de ambiente antes de qualquer perfil OAuth armazenado. Também é possível criar perfis nomeados e vinculá-los a diretórios diferentes ao trabalhar com contas de clientes ou da empresa.

Mantenha genérico o texto enviado a cf cli search. Informe a ação e o tipo de recurso, não um domínio, endereço de e-mail, ID de conta ou token.

node --version
npm i -g cf
cf --version

cf auth login
cf auth whoami

cf cli search "list zones in an account"
cf zones list | jq -e 'type == "array" and all(.[]; has("name") and has("status"))'

Hoje, a busca coloca cf zones list em primeiro lugar para essa tarefa. A última linha funciona como prova: ela faz uma chamada somente leitura à API e só termina com sucesso se o resultado for um array JSON cujos itens contenham name e status. Se houver várias contas, selecione um perfil nomeado com --profile ou filtre o comando com --account-id.

Não cole um token no histórico do shell. Coloque um token com escopo restrito no ambiente de processo usado pela CI e conceda somente as permissões de leitura ou gravação exigidas pela tarefa. OAuth costuma ser a opção mais confortável para uma sessão individual no terminal, pois o cf consegue renovar o perfil selecionado.

O que o teste descartável comprovou

Uma instalação nova e isolada feita em 29 de setembro retornou cf v1.0.0-beta.5. A busca de comandos devolveu um array JSON válido com cinco itens, o cf init criou um projeto de Worker tipado e tanto o projeto novo quanto um projeto de teste Vite migrado compilaram localmente. O ambiente não continha uma credencial de conta de teste da Cloudflare; por isso, a consulta autenticada de zonas e uma implantação não foram registradas como testes concluídos.

Esse limite é importante. Uma compilação local bem-sucedida valida o caminho do projeto, mas não comprova que o token tenha as permissões corretas em produção nem que uma implantação tenha chegado à Cloudflare.

Crie um Worker pequeno e confira o que o cf gerou

O cf init é o teste limpo mais rápido para o novo fluxo de projeto. Em um diretório vazio, ele cria o código-fonte TypeScript, cloudflare.config.ts, vite.config.ts, scripts de pacote e tipos de Worker gerados. Depois, cf build delega ao Cloudflare Vite Plugin e produz uma saída de build padronizada.

cf init hello-cf --package-manager npm
cd hello-cf
npm run build

# In a copied existing Vite Worker:
cf migrate --dry-run
cf migrate
npm run build

Abra cloudflare.config.ts depois de seguir qualquer um dos caminhos. Em um Worker básico, deve haver um bloco worker com nome, data de compatibilidade, ponto de entrada e bindings tipados. Um binding de texto é declarado pela API de configuração, em vez de ser copiado para vários blocos de ambiente. É aí que o TypeScript faz diferença: um campo digitado incorretamente pode gerar um aviso no editor antes de causar uma falha na implantação.

A configuração Vite gerada não é mero enfeite. O Vite agora é o caminho padrão de desenvolvimento local e build do cf, e a Cloudflare recomenda seu plugin Vite tanto para frontends quanto para APIs de backend. No projeto descartável, npm run build delegou ao Vite e foi concluído. A implantação ficou de fora de propósito. Depois da revisão e do teste da conta, o comando documentado cf deploy compila e envia o projeto por padrão.

Quando o Wrangler continua necessário

Não remova o Wrangler só porque a instalação do cf funcionou. A decisão correta de migração depende do caminho de build do projeto.

Em um Worker Vite existente, cf migrate pode converter uma configuração Wrangler em JSON, JSONC ou TOML para cloudflare.config.ts. O comando detecta o plugin Vite da Cloudflare ao lado da configuração do Wrangler e escolhe o caminho Vite. Se o plugin não estiver declarado, as versões beta atuais usam o bundler do Wrangler. Execute a prévia, leia todos os itens de acompanhamento e faça a migração em uma cópia ou branch limpa antes de mexer no projeto de trabalho.

Para Workers JavaScript que ainda dependem do comportamento do esbuild no Wrangler, o cf delega o desenvolvimento e a implantação ao Wrangler. O mesmo vale para Workers em Rust e Python. Isso é compatibilidade, não sinal de que a migração falhou. A equipe adota o cf como porta de entrada, enquanto a ferramenta de build já comprovada permanece no fluxo.

O cronograma de suporte da Cloudflare também pode ser mal interpretado. A manutenção do Wrangler está planejada por 18 meses após o fim do open beta, e não por 18 meses a partir do lançamento de 28 de setembro. Não há motivo para forçar um projeto Rust, Python ou esbuild a migrar para Vite esta semana.

Sete fluxos que entregam valor primeiro

Os melhores casos de uso iniciais têm algo em comum: substituem tarefas repetidas de busca e formatação sem liberar acesso amplo de gravação logo no primeiro dia.

1. Uma agência padroniza a verificação de contas

Uma agência pode vincular um perfil OAuth nomeado ao diretório de cada cliente, buscar o comando de leitura relevante e enviar o mesmo formato JSON a um script de revisão. Isso reduz a inconsistência que aparece quando uma pessoa navega por painéis enquanto outra mantém um comando curl personalizado. O ganho é a repetibilidade entre clientes, sobretudo em DNS, zonas, configurações de conta e revisões de segurança.

2. Uma equipe de plataforma oferece aos agentes uma interface segura da Cloudflare

Quem lidera a plataforma pode criar uma regra em AGENTS.md para cf cli search, permitir comandos de leitura por padrão e exigir aprovação humana para mutações. A busca evita que o agente tente adivinhar uma sintaxe antiga do Wrangler, enquanto o JSON mantém a saída compacta e filtrável. Isso é especialmente útil quando a equipe já pede aos agentes que verifiquem status de build, logs, filas ou recursos de conta e quer uma interface previsível.

3. A pessoa de plantão reúne o contexto do incidente

Durante um incidente, é possível buscar a leitura certa de logs, zona, ruleset ou analytics em vez de percorrer vários painéis de produto. O comando exato ainda importa e as permissões continuam valendo, mas a etapa de descoberta passa a ser local e a resposta já fica pronta para o jq. Para equipes que executam tarefas como o Cloudflare Browser Run, isso encurta o caminho entre uma tarefa que falhou e o estado da conta ao redor dela.

4. Um fundador inicia um Worker sem desenhar toda a cadeia de ferramentas

Um fundador que esteja criando um webhook, serviço de redirecionamento ou pequena API interna pode rodar cf init, inspecionar o Worker e o binding gerados e então usar o build do Vite sem selecionar cada pacote separadamente. O projeto pode começar no Workers Free. Se precisar do plano pago, a cobrança mínima atual é de $5 por conta ao mês. O ganho é um caminho curto até um artefato local que possa ser revisado, não a promessa de que as operações em produção serão gratuitas.

5. Uma equipe Vite converte a configuração sem reescrever o aplicativo

Uma equipe de engenharia com um Worker baseado em Vite pode executar cf migrate --dry-run em uma cópia, conferir o TypeScript gerado e fazer o build antes de alterar a implantação. Isso ajuda especialmente quando os blocos de ambiente se tornaram repetitivos. O novo formato consegue calcular a configuração a partir de uma base compartilhada, mas a equipe deve migrar o comportamento, não apenas a sintaxe do arquivo.

6. Uma equipe de dados ou operações leva consultas da Cloudflare para relatórios

Como os resultados estruturados são JSON por padrão, é possível encaminhar uma consulta para o jq, um carregador de data warehouse ou um relatório agendado sem extrair dados de uma tabela Unicode. O ganho para o negócio é prosaico, no melhor sentido: menos adaptadores de saída e menos regras frágeis de parsing. Use um token de leitura com escopo restrito e não exponha a saída do comando em logs públicos da CI.

7. Uma equipe de Workers inspeciona recursos locais antes de tocar na produção

Os comandos compatíveis aceitam --local e conversam com uma instância Miniflare de curta duração, apoiada em estado local. Isso inclui operações definidas em KV, D1 e R2. Se não houver equivalente local, o cf retorna um erro em vez de seguir silenciosamente para a produção. Uma equipe que desenvolve um Cloudflare AI Search Worker pode usar esse limite para testar dados locais de apoio sem transformar um comando de desenvolvimento em uma gravação remota.

Dois produtos que vale a pena construir em torno do cf

A oportunidade de produto não é o CLI em si. Ela está na camada de controle de que as equipes ainda precisam para lidar com uma superfície de API tão ampla.

Melhor oportunidade: controle de mudanças na Cloudflare para agências

Crie uma camada enxuta de aprovação e evidências para agências ou pequenas equipes de plataforma que administram várias contas da Cloudflare. A pessoa propõe uma mudança em DNS, zona, WAF ou Worker; o produto usa o cf para coletar o estado JSON atual, mostra um diff legível, solicita aprovação, executa com um perfil de escopo restrito e armazena o resultado.

O sinal de demanda é modesto, mas comercial: cloudflare dns management recebe cerca de 170 buscas mensais nos EUA, tem CPC de $6 e exibe lances no topo da página entre $3.85 e $36.64. A governança geral de infraestrutura também comporta orçamentos reais. A Spacelift lista o Starter+ por $20,000. Um produto específico para Cloudflare pode ser mais barato e simples de adotar porque não precisa governar todas as nuvens.

A menor versão vendável seria um aplicativo GitHub ou uma fila de revisão hospedada para mudanças em DNS e Workers, com isolamento de perfis, uma lista de comandos permitidos, JSON de antes e depois e rollback com um clique quando a API correspondente oferecer esse recurso. O desafio é construir uma vantagem defensável: o cf já fornece a cobertura de comandos, então o valor difícil de copiar está em políticas, evidências, permissões e no fluxo das agências. Uma interface gráfica superficial será copiada rapidamente.

Recurso útil: diagnóstico de prontidão para migrar Workers

Crie um scanner que classifique um repositório como Vite nativo, esbuild apoiado pelo Wrangler, Python ou Rust; depois, ele executa a prévia segura da migração e transforma os itens de acompanhamento em um checklist para pull request. O público comprador são equipes com um portfólio de Workers, não uma única pessoa migrando um projeto pequeno.

A demanda é pequena demais para sustentar uma empresa inteira. cloudflare worker deployment recebe cerca de 10 buscas mensais nos EUA, embora a consulta tenha intenção transacional. O MVP sensato é um recurso pago dentro de um produto de operações da Cloudflare ou de um serviço de migração: varredura do repositório, cf migrate --dry-run, verificação do build e um relatório claro de fallback para o Wrangler. O problema é o ritmo das mudanças durante o beta. O scanner precisa acompanhar de perto as versões do cf e do Cloudflare Vite Plugin; caso contrário, suas recomendações envelhecem mais rápido que os projetos analisados.

Limites e a decisão sem rodeios

Use o cf agora para descobrir comandos, fazer consultas de conta com JSON desde a origem, criar Workers Vite e testar migrações com cautela. Mantenha o Wrangler instalado onde o cf delega a ele e deixe as gravações em produção atrás de escopos explícitos e revisão.

O open beta ainda não transforma cloudflare.config.ts em uma fonte única de verdade para a conta inteira. O ponto de partida são os Workers. Ele também não converte toda operação da API da Cloudflare em um fluxo de negócio seguro. A cobertura completa aumenta o alcance de um token, tornando o princípio do menor privilégio e a revisão de comandos ainda mais importantes.

A opção local tem limites intencionais. As operações compatíveis de KV, D1, R2, Durable Object e Workflow podem usar o estado local, mas uma operação sem equivalente no explorador local retorna erro. Essa é uma boa propriedade de segurança, porém significa que --local não é um espelho offline universal da Cloudflare.

Por fim, versões beta mudam rapidamente. Fixe a versão do cf nas dependências do projeto para o trabalho em equipe, revise a configuração gerada e faça a CI usar a versão local do projeto. Uma instalação global é prática para descoberta; uma versão fixada garante o mesmo comportamento a todas as pessoas que colaboram.

Se sua equipe precisa de um caminho seguro de automação da Cloudflare, do projeto à implementação, conheça os sistemas de IA em produção.