Guia prático do novo cf CLI da Cloudflare

O cf é a ferramenta de linha de comando da Cloudflare para toda a API da Cloudflare. Ele foi lançado em beta aberto em 28 de setembro de 2026 e é instalado com npm i -g cf no Node.js 22.18 ou superior.

Se você faz deploy de Workers com o Wrangler, provavelmente ainda recorre ao dashboard para DNS, zonas e configurações que o Wrangler nunca cobriu. O cf cobre as duas coisas, os recursos da sua conta e os seus projetos de Worker, a partir de um único binário. Este guia mostra como instalá-lo, interpretar sua saída, escrever o novo arquivo de configuração em TypeScript, fazer deploy e migrar um Worker existente. Se precisar revisar os conceitos de Workers antes, comece por este guia para iniciantes sobre Cloudflare Workers.

Qual é a diferença entre o cf e o Wrangler?

O cf substitui uma CLI que cresceu um comando de cada vez por outra gerada a partir dos schemas OpenAPI da Cloudflare. O anúncio de lançamento atribui ao cf mais de 3.000 operações de API, contra cerca de 280 no Wrangler. A documentação do cf faz a contagem de outra forma: mais de 2.900 comandos. A Cloudflare desenvolveu o cf pensando em agentes de programação, mas todos os comandos funcionam da mesma forma quando você os digita manualmente.

A entrada do changelog alerta que comandos, configuração e o Build Output ainda podem mudar antes da versão estável.

Como instalar o cf e fazer login?

Instale o pacote cf pelo npm e, em seguida, autentique-se com cf auth login. Outras ferramentas também instalam um comando chamado cf, então certifique-se de que você está usando o pacote oficial, que aponta para o repositório cloudflare/cf.

npm i -g cf
cf --version

cf auth login     # add --no-browser over SSH or in a container
cf auth whoami

De acordo com a documentação de primeiros passos, o pacote disponibiliza a mesma CLI com dois nomes, cf e cloudflare. Se outro programa no seu PATH já responder por cf, use cloudflare. Para fazer login, o cf exibe um link e um código de uso único e, em seguida, abre esse link no navegador para que você aprove o acesso. O cf armazena suas próprias credenciais, então um login feito no Wrangler não é reaproveitado.

Em CI, defina CLOUDFLARE_API_TOKEN e CLOUDFLARE_ACCOUNT_ID. Um token definido dessa forma tem prioridade sobre qualquer login salvo.

Comece com um comando somente leitura:

cf zones list

Como ler e filtrar a saída JSON do cf?

A maioria dos comandos do cf grava seus resultados no stdout como JSON, enquanto as mensagens de progresso e status vão para o stderr. Assim, você pode salvar os resultados em um arquivo ou encaminhá-los para o jq sem nenhuma flag adicional.

cf zones list > zones.json        # results only; status stays on stderr
cf zones list | jq .              # inspect the shape
cf zones list | jq '.[].id'       # print each zone's id
cf zones list --name example.com  # look up one domain

Como mostra a documentação de gerenciamento de recursos, cf zones list retorna um array JSON em que cada zona tem um campo id. Os comandos que operam dentro de uma zona recebem --zone ou sua forma abreviada -z, e aceitam tanto um ID de zona quanto um nome de domínio:

cf dns records list --zone example.com
cf dns records list -z example.com

Encontre comandos com cf cli search

Para encontrar um comando, execute cf cli search com uma descrição da tarefa em linguagem natural e, em seguida, abra a ajuda do comando sugerido. Segundo a documentação para agentes, cf cli search retorna até cinco resultados como um array JSON, com a melhor correspondência primeiro. A busca é feita na sua própria máquina, então não é preciso estar logado.

cf cli search "create a DNS record"
cf dns --help
cf complete zsh >> ~/.zshrc   # shell completion

O --help funciona em todos os níveis da árvore de comandos.

Como configurar Workers com o cloudflare.config.ts?

O cloudflare.config.ts é o arquivo de configuração em TypeScript do cf para Workers. Ele importa defineConfig de cf/config, exporta o resultado como default e declara bindings e triggers por meio de helpers tipados que o seu editor consegue autocompletar. A referência de configuração programática destaca que o arquivo é um módulo TypeScript comum, então você pode usar imports, funções, variáveis de ambiente e valores assíncronos nele.

O primeiro exemplo do post de lançamento importa o módulo do Worker com o import attribute with { type: "cf-worker" } e, em seguida, define name, entrypoint e compatibilityDate. Nos trechos abaixo, // ... representa esses campos. Este trecho resumido do exemplo de bindings do post de lançamento passa uma função para defineConfig, de modo que os valores possam variar conforme o mode:

import { bindings, defineConfig } from "cf/config";

export default defineConfig(({ mode }) => ({
  worker: {
    // ...
    env: {
      API_TOKEN: bindings.secret(),
      DATABASE: bindings.d1({ name: `example-${mode}-database` }),
      UPLOADS: bindings.r2({ name: `example-${mode}-uploads` }),
      JOBS: bindings.queue<{ userId: string }>({
        name: `example-${mode}-jobs`,
      }),
      AI: bindings.ai(),
    },
  },
}));

O exemplo completo também usa bindings.text, bindings.kv, bindings.vectorize e bindings.worker. Os triggers ficam em um único array. Este trecho passa um objeto simples para defineConfig:

import { defineConfig, triggers } from "cf/config";

export default defineConfig({
  worker: {
    // ...
    triggers: [
      triggers.fetch({ pattern: "example.com/*" }),
      triggers.scheduled({ schedule: "0 * * * *" }),
      triggers.queue({ name: "jobs", maxBatchSize: 10 }),
    ],
  },
});

A versão do post de lançamento adiciona uma entrada triggers.email. A referência também lista triggers.connect, que cobre raw sockets. No post de lançamento, a Cloudflare afirma que planeja permitir que esse arquivo também configure zonas e DNS. Por enquanto, o export default cobre um Worker, aplicações de Container e configurações da conta.

Init, deploy e migração

Use cf init para um novo projeto, cf deploy para publicá-lo e cf migrate para um projeto existente do Wrangler.

cf init my-worker      # or `cf init .` inside an existing app
cf deploy

O cf init cria o cloudflare.config.ts e o vite.config.ts e, em uma aplicação Vite existente, instala o @cloudflare/vite-plugin. Se executado sem argumentos, ele para e solicita um diretório. Segundo a documentação de deploy, uma única chamada de cf deploy faz o build e valida o projeto, determina quais credenciais e conta usar e, em seguida, faz upload de uma nova Worker Version e a coloca no ar. Um site estático não precisa de arquivo de configuração antes do seu primeiro cf deploy.

Se o seu projeto tiver um wrangler.toml, wrangler.json ou wrangler.jsonc, faça a migração antes de executar cf dev, cf build ou cf deploy. Esses três comandos consideram apenas o cloudflare.config.ts e ignoram qualquer arquivo de configuração do Wrangler.

cf migrate --dry-run
cf migrate

O cf migrate lê TOML diretamente, então não é preciso converter os arquivos antigos antes. Se você quiser apenas uma visualização em JSON de um wrangler.toml legado, use um conversor de TOML para JSON. O guia do cf para usuários do Wrangler explica que a migração mantém o bundler do Wrangler, a menos que o projeto já use o plugin Vite da Cloudflare, de modo que a mudança para o Vite é opcional. Quando mantém o bundler do Wrangler, a migração gera um wrangler.config.ts, e a documentação de migração informa que o pacote do Worker precisa ter o Wrangler 4.136.0 ou superior instalado. O post de lançamento acrescenta que Workers em Rust e Python também continuam delegando ao Wrangler.

O que acontece com o Wrangler?

O Wrangler continua funcionando por enquanto, mas já tem data para acabar. Quando o beta aberto do cf terminar, a Cloudflare planeja lançar uma última versão major do Wrangler que direciona os usuários para o cf e, a partir daí, manter o Wrangler por 18 meses. A Cloudflare ainda não anunciou quando o beta termina, então esses 18 meses ainda não têm uma data definida no calendário.

A adoção do Vite como build padrão se encaixa em um movimento mais amplo em direção ao Vite no ecossistema de Workers.

Conclusão

Você pode instalar o cf junto com o Wrangler: os comandos de recursos funcionam em um projeto não migrado, e a troca só passa a importar quando você transfere os builds de um Worker para ele. Instale o pacote oficial, execute cf zones list | jq . para ver a saída com seus próprios olhos e, em seguida, teste cf migrate --dry-run em uma branch de um Worker não crítico antes que o beta termine e comece o período de manutenção do Wrangler.

Perguntas frequentes

Como usar o cf com mais de uma conta da Cloudflare?

Use perfis nomeados. Execute cf auth create work para criar um perfil e fazer login nele e, em seguida, cf auth activate work para vinculá-lo à pasta atual e a todas as subpastas. Passe --profile work para usar um perfil em um único comando e cf auth list para ver todos os perfis. Uma variável de ambiente CLOUDFLARE_API_TOKEN tem prioridade sobre todos os perfis e bloqueia os comandos de gerenciamento de perfis enquanto estiver definida.

O cf consegue ler credenciais de um arquivo .env?

Sim. Os comandos de API podem obter CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID e CLOUDFLARE_ZONE_ID de um arquivo .env na pasta em que você os executa. O cf considera apenas o .env, não o .env.local, então certifique-se de que o .env esteja listado no .gitignore. Um token carregado dessa forma tem prioridade sobre qualquer perfil ou login armazenado. O cf não suporta a Global API Key, então use um API token com escopo definido.

Como migrar um projeto do Wrangler dentro de um monorepo?

Passe o caminho do arquivo de configuração para o cf migrate, por exemplo cf migrate packages/api/wrangler.jsonc --dry-run, e depois execute o mesmo comando sem --dry-run. Sem um caminho, o cf migrate espera exatamente um wrangler.json, wrangler.jsonc ou wrangler.toml no diretório atual. Ele grava seus arquivos ao lado do arquivo de configuração, escolhe o bundler com base no package.json, a menos que você passe --bundler vite ou --bundler wrangler, e exige --force se a worktree do Git não estiver limpa.

O que acontece se eu executar cf deploy em um projeto do Wrangler antes de migrar?

O cf ignora o wrangler.jsonc e o wrangler.toml, então pode configurar o projeto por conta própria e alterar arquivos como o package.json. Para reverter, execute git status, restaure cada arquivo alterado com git restore e exclua os arquivos novos, como cloudflare.config.ts, wrangler.config.ts e o diretório .cloudflare. Em seguida, execute cf migrate, que não roda enquanto existir um cloudflare.config.ts.