Cloudflare CLI: desenvolver e publicar com o cf
A Cloudflare CLI é a ferramenta de linha de comando cf para administrar recursos da Cloudflare e trabalhar com projetos Workers. Ela coordena o desenvolvimento, o build e a publicação do seu projeto usando a configuração cloudflare.config.ts e a ferramenta de build compatível.
Ficha e sumário da página
- Referência técnica
- cf 1.0.0-beta.32
- Revisão
- 15 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
O comando cf reúne projetos e recursos da Cloudflare
O pacote publicado no npm se chama cf e fornece o comando de mesmo nome. Seu código fica no repositório oficial cloudflare/cf, dentro de packages/cli, mantido pela Cloudflare. A licença do pacote permite escolher entre MIT e Apache-2.0. A versão de referência desta explicação é a 1.0.0-beta.32, ainda anterior à versão estável.
Você usa a mesma interface para trabalhar no código de um Worker ou consultar recursos pela API pública da Cloudflare. Os comandos de recursos alcançam configurações de zonas e registros de DNS e domínios. Já os comandos de projeto acompanham o código local até sua publicação. A documentação mantém essas duas funções separadas porque administrar um recurso existente não exige converter o projeto que o utiliza.
Um exemplo é cf r2 buckets list, que consulta os buckets de armazenamento R2 do cadastro selecionado na Cloudflare. Esse comando administra recursos remotos. O desenvolvimento local de um Worker usa outra família de comandos, com leitura da configuração do projeto e participação da ferramenta de build.
Desenvolvimento, build e publicação
O cf dev coordena o ambiente de desenvolvimento. O cf build produz o resultado que pode ser enviado à plataforma. O cf deploy publica o projeto e também pode executar o build antes do envio. Essa divisão permite examinar o resultado da construção antes de alterar a versão que atende às requisições.
Projeto local
cloudflare.config.tsDeclara o Worker e as ligações com os serviços da Cloudflare.
Desenvolvimento
cf devAciona a ferramenta compatível com o projeto para desenvolver localmente.
Build
cf buildGera o Build Output em .cloudflare/output/v0/.
Publicação
cf deployEnvia o projeto para execução na Cloudflare.
O cf delega o servidor de desenvolvimento e o empacotamento ao framework detectado ou a uma ferramenta instalada no projeto. Num projeto Vite compatível, isso pode significar chamar vite ou vite build pelo gerenciador de pacotes. O Cloudflare Vite plugin e o Wrangler também participam desse trabalho conforme as dependências declaradas.
Há uma diferença relevante para scripts existentes: o cf build não executa automaticamente o script build do seu package.json. Se esse script também verifica tipos, você precisa manter essa verificação na automação que chama o build. Um resultado compilado pode existir mesmo quando uma checagem adicional do repositório ainda não foi executada.
O arquivo cloudflare.config.ts
O cloudflare.config.ts descreve o projeto com TypeScript. Seu export padrão aceita uma configuração que declara o Worker e pode incluir ajustes do cadastro na Cloudflare e aplicações de Containers. Os helpers de cf/config, como defineConfig, fornecem tipos para o editor completar campos e indicar configurações incompatíveis durante a escrita.
No Worker, name identifica o programa publicado e compatibilityDate fixa a data de compatibilidade do runtime. O entrypoint identifica o módulo de entrada quando há código para executar. Os bindings ligam o Worker a serviços da Cloudflare. Assim você encontra no arquivo tanto a identidade do programa quanto as conexões disponíveis ao código em execução.
Por ser um módulo TypeScript, o arquivo pode usar funções e valores calculados. O modo selecionado com --mode permite variar a configuração entre ambientes. A configuração programática está em beta aberta, portanto sua sintaxe ainda pode mudar. A descrição dos Workers continua válida para a execução na plataforma, mas os nomes dos campos diferem dos arquivos tradicionais do Wrangler.
A relação com o Wrangler
O Wrangler continua sendo a CLI de projetos Workers configurados com arquivos como wrangler.jsonc e wrangler.toml. O cf amplia o alcance aos recursos da API pública e adota o cloudflare.config.ts para os projetos. A migração preserva conceitos da plataforma, como bindings e versões publicadas, enquanto altera a representação local da configuração.
Você pode manter o Wrangler no desenvolvimento e no deploy de um projeto existente enquanto usa o cf para consultar recursos remotos. O login do Wrangler não é reaproveitado pelo cf, que tem autenticação própria. Em automações, as duas ferramentas aceitam as variáveis CLOUDFLARE_API_TOKEN e CLOUDFLARE_ACCOUNT_ID.
O comando cf migrate converte a configuração do Wrangler e indica ajustes que exigem edição manual. Isso merece atenção porque a configuração automática do cf não interpreta o arquivo antigo do Wrangler. Executar comandos de projeto antes dessa conversão pode criar uma configuração que desconsidera o ponto de entrada e os bindings anteriores.
O que ainda pode mudar na beta
A Cloudflare identifica como sujeitos a mudança os comandos, a configuração e o formato Build Output. O aviso alcança a ferramenta e seus arquivos, sem significar que os próprios Workers estejam em beta. Por isso a referência cf 1.0.0-beta.32 identifica a CLI consultada, não uma versão da plataforma inteira.
Na integração contínua, o cf aceita token de API para autenticar a publicação. A documentação também apresenta o uso de --prebuilt para publicar um resultado construído anteriormente e de --dry-run para conferir o deploy. Você pode manter a versão da CLI nas dependências do repositório e registrar a configuração junto do código, tornando a publicação reproduzível com aquela release.
O build e deploy pelo GitHub continua sendo outro modo de acionar a publicação. Ao adaptar uma automação para o cf, a conferência precisa abranger a autenticação, os scripts adicionais de validação e a configuração convertida. Um comando de deploy aceito não confirma sozinho que todas as verificações anteriores do projeto foram preservadas.
Continue na comunidade
Leve ao Discord da Promovaweb o domínio que ainda responde pelo registrador antigo ou o deploy que falhou no build. Com o log do Wrangler na conversa, a comunidade compara o seu caso com projetos parecidos.
Uma VPS ao lado da borda
Um Worker não mantém processo ligado nem grava em disco próprio. O banco, as filas e o n8n rodam numa VPS da StayCloud em São Paulo, com acesso root e disco NVMe. A Cloudflare fica na frente pelo proxy.
Link de parceiro da Promovaweb.