Guía práctica de cf, la nueva CLI de Cloudflare

cf es la herramienta de línea de comandos de Cloudflare para toda la API de Cloudflare. Se lanzó en beta abierta el 28 de septiembre de 2026 y se instala con npm i -g cf en Node.js 22.18 o posterior.

Si despliegas Workers con Wrangler, probablemente sigues abriendo el dashboard para gestionar DNS, zonas y configuraciones que Wrangler nunca cubrió. cf cubre ambas cosas, los recursos de tu cuenta y tus proyectos de Workers, desde un único binario. Esta guía te explica cómo instalarlo, interpretar su salida, escribir el nuevo archivo de configuración en TypeScript, desplegar y migrar un Worker existente. Si antes necesitas repasar los conceptos básicos de Workers, empieza por esta guía para principiantes de Cloudflare Workers.

¿En qué se diferencia cf de Wrangler?

cf sustituye a una CLI que fue creciendo comando a comando por otra generada a partir de los esquemas OpenAPI de Cloudflare. El anuncio del lanzamiento atribuye a cf más de 3.000 operaciones de la API, frente a unas 280 en Wrangler. La documentación de cf lo cuantifica de otra forma: más de 2.900 comandos. Cloudflare diseñó cf pensando en los agentes de programación, pero todos los comandos funcionan exactamente igual cuando los escribes tú.

La entrada del changelog advierte que los comandos, la configuración y el Build Output aún pueden cambiar antes de la versión estable.

¿Cómo se instala cf y se inicia sesión?

Instala el paquete cf desde npm y, a continuación, autentícate con cf auth login. Hay otras herramientas que también instalan un comando llamado cf, así que asegúrate de usar el paquete oficial, que enlaza al repositorio cloudflare/cf.

npm i -g cf
cf --version

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

Según la documentación de primeros pasos, el paquete ofrece la misma CLI con dos nombres: cf y cloudflare. Si otra herramienta de tu PATH ya responde a cf, invócala como cloudflare. Para iniciar sesión, cf muestra un enlace y un código de un solo uso, y después abre ese enlace en tu navegador para que lo apruebes. cf almacena sus propias credenciales, por lo que un inicio de sesión en Wrangler no se traslada.

En CI, define en su lugar CLOUDFLARE_API_TOKEN y CLOUDFLARE_ACCOUNT_ID. Un token definido de esta forma tiene prioridad sobre cualquier sesión guardada.

Empieza con un comando de solo lectura:

cf zones list

¿Cómo se lee y filtra la salida JSON de cf?

La mayoría de los comandos de cf escriben sus resultados en stdout como JSON, mientras que los mensajes de progreso y estado van a stderr. Así, puedes guardar los resultados en un archivo o canalizarlos a jq sin flags adicionales.

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 muestra la documentación de gestión de recursos, cf zones list devuelve un array JSON en el que cada zona tiene un campo id. Los comandos que operan dentro de una zona aceptan --zone o su forma abreviada -z, y admiten tanto un ID de zona como un nombre de dominio:

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

Buscar comandos con cf cli search

Para encontrar un comando, ejecuta cf cli search con una descripción de la tarea en lenguaje natural y, después, abre la ayuda del comando que te sugiera. Según la documentación para agentes, cf cli search devuelve hasta cinco coincidencias como un array JSON, con la más relevante en primer lugar. La búsqueda se realiza en tu propia máquina, así que no necesitas haber iniciado sesión.

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

--help funciona en todos los niveles del árbol de comandos.

¿Cómo se configuran los Workers con cloudflare.config.ts?

cloudflare.config.ts es el archivo de configuración en TypeScript de cf para Workers. Importa defineConfig desde cf/config, exporta el resultado como exportación por defecto y declara bindings y triggers mediante helpers tipados que tu editor puede autocompletar. La referencia de configuración programática señala que el archivo es un módulo TypeScript normal, por lo que puedes usar en él imports, funciones, variables de entorno y valores asíncronos.

El primer ejemplo del anuncio de lanzamiento importa el módulo del Worker con el atributo de importación with { type: "cf-worker" } y, a continuación, define name, entrypoint y compatibilityDate. En los fragmentos siguientes, // ... representa esos campos. Este extracto recortado del ejemplo de bindings del anuncio pasa una función a defineConfig para que los valores puedan variar según el 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(),
    },
  },
}));

El ejemplo completo también utiliza bindings.text, bindings.kv, bindings.vectorize y bindings.worker. Los triggers se definen en un único array. Este extracto pasa un objeto literal a 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 }),
    ],
  },
});

La versión del anuncio de lanzamiento añade una entrada triggers.email. La referencia también incluye triggers.connect, que cubre los sockets raw. En el anuncio de lanzamiento, Cloudflare indica que tiene previsto que este archivo también permita configurar zonas y DNS. Por ahora, la exportación por defecto cubre un Worker, aplicaciones de Containers y la configuración de la cuenta.

Init, deploy y migrate

Usa cf init para un proyecto nuevo, cf deploy para publicarlo y cf migrate para un proyecto de Wrangler existente.

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

cf init crea cloudflare.config.ts y vite.config.ts, y en una aplicación Vite existente instala @cloudflare/vite-plugin. Si se ejecuta sin argumentos, se detiene y pide un directorio. Según la documentación de despliegue, una sola llamada a cf deploy compila y valida el proyecto, determina qué credenciales y qué cuenta usar, y después sube una nueva Worker Version y la pone en producción. Un sitio estático no necesita ningún archivo de configuración antes de su primer cf deploy.

Si tu proyecto tiene un wrangler.toml, wrangler.json o wrangler.jsonc, mígralo antes de ejecutar cf dev, cf build o cf deploy. Esos tres comandos solo tienen en cuenta cloudflare.config.ts e ignoran cualquier archivo de configuración de Wrangler.

cf migrate --dry-run
cf migrate

cf migrate lee TOML directamente, por lo que no necesitas convertir antes los archivos antiguos. Si solo quieres ver un wrangler.toml heredado en formato JSON, utiliza un conversor de TOML a JSON. La guía de cf para usuarios de Wrangler explica que la migración mantiene el bundler de Wrangler, salvo que el proyecto ya utilice el plugin de Vite de Cloudflare, de modo que pasarse a Vite es opcional. Cuando mantiene el bundler de Wrangler, genera un wrangler.config.ts, y la documentación de migración indica que el paquete del Worker necesita tener instalado Wrangler 4.136.0 o posterior. El anuncio de lanzamiento añade que los Workers escritos en Rust y Python también siguen delegando en Wrangler.

¿Qué pasará con Wrangler?

Wrangler sigue funcionando por ahora, pero su final ya está decidido. Cuando termine la beta abierta de cf, Cloudflare tiene previsto publicar una última versión mayor de Wrangler que redirija a los usuarios a cf y, a partir de ese momento, mantener Wrangler durante 18 meses. Cloudflare no ha anunciado cuándo terminará la beta, así que esos 18 meses todavía no tienen fecha en el calendario.

Que Vite pase a ser el sistema de build por defecto encaja con una tendencia más amplia hacia Vite en el ecosistema de Workers.

Conclusión

Puedes instalar cf junto a Wrangler: sus comandos de recursos funcionan en un proyecto sin migrar, y el cambio solo importa cuando trasladas a cf los builds de un Worker. Instala el paquete oficial, ejecuta cf zones list | jq . para ver la salida por ti mismo y, después, prueba cf migrate --dry-run en una rama de un Worker no crítico antes de que termine la beta y comience el periodo de mantenimiento de Wrangler.

Preguntas frecuentes

¿Cómo uso cf con más de una cuenta de Cloudflare?

Usa perfiles con nombre. Ejecuta cf auth create work para crear un perfil e iniciar sesión en él y, después, cf auth activate work para vincularlo a la carpeta actual y a todas sus subcarpetas. Pasa --profile work para usar un perfil en un único comando, y cf auth list para ver todos los perfiles. Una variable de entorno CLOUDFLARE_API_TOKEN tiene prioridad sobre todos los perfiles y bloquea los comandos de gestión de perfiles mientras esté definida.

¿Puede cf leer credenciales desde un archivo .env?

Sí. Los comandos de la API pueden obtener CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID y CLOUDFLARE_ZONE_ID de un archivo .env ubicado en la carpeta desde la que los ejecutas. cf solo lee .env, no .env.local, así que asegúrate de que .env figure en .gitignore. Un token cargado de esta forma tiene prioridad sobre cualquier perfil o sesión guardada. cf no admite la Global API Key, así que utiliza en su lugar un API token con permisos acotados.

¿Cómo migro un proyecto de Wrangler dentro de un monorepo?

Pasa la ruta del archivo de configuración a cf migrate, por ejemplo cf migrate packages/api/wrangler.jsonc --dry-run, y después ejecuta el mismo comando sin --dry-run. Sin una ruta, cf migrate espera encontrar exactamente un wrangler.json, wrangler.jsonc o wrangler.toml en el directorio actual. Genera sus archivos junto al archivo de configuración, elige el bundler a partir de package.json salvo que pases --bundler vite o --bundler wrangler, y requiere --force si el worktree de Git tiene cambios sin confirmar.

¿Qué ocurre si ejecuto cf deploy en un proyecto de Wrangler antes de migrarlo?

cf ignora wrangler.jsonc y wrangler.toml, por lo que puede configurar el proyecto por su cuenta y modificar archivos como package.json. Para recuperarte, ejecuta git status, restaura cada archivo modificado con git restore y elimina los archivos nuevos, como cloudflare.config.ts, wrangler.config.ts y el directorio .cloudflare. Después, ejecuta cf migrate, que no se ejecuta mientras exista un cloudflare.config.ts.