Cómo usar la CLI cf de Cloudflare con Claude Code: instalación, desarrollo local y migración probados (beta.26)

Nota de versión: probado con cf 1.0.0-beta.26 el 2026-10-31. cf está en beta, así que los comandos y la salida pueden cambiar.

Cloudflare publicó el 2026-09-28 una nueva herramienta de línea de comandos llamada cf, en beta abierta. En esta guía explico cómo instalar Cloudflare CLI y qué pasó cuando la probé: la instalación, el aviso para agentes en --help, la búsqueda de comandos, cf init, cf dev, cf build y cf migrate sobre un proyecto antiguo de Wrangler. También explico cómo prepararla para que Claude Code (o Codex) despliegue un Worker con ella.

Una aclaración desde el principio: no ejecuté cf auth login ni cf deploy, porque los dos necesitan una cuenta de Cloudflare. Lo que cuento sobre el inicio de sesión y el despliegue sale de la documentación oficial, y lo vuelvo a indicar en esa sección.

Qué es cf y qué relación tiene con Wrangler

cf es una sola CLI para toda la API de Cloudflare, no solo para Workers. El changelog habla de más de 2.900 comandos, y el blog del lanzamiento dice que cubre más de 3.000 operaciones de la API. Como referencia, según el blog Wrangler cubre unas 280. Los comandos se generan a partir de las definiciones de la API de Cloudflare, así que DNS, R2, D1, Access, AI Gateway y el resto están junto a los comandos de Workers.

El blog también explica el motivo: a finales de septiembre de 2026, los agentes ya generaban el 48% del uso de Wrangler (en marzo era una cuarta parte). Por eso cf está pensada para que un agente encuentre el comando correcto por su cuenta. Cada comando devuelve JSON por stdout y deja los mensajes en stderr.

Wrangler no desaparece todavía. Según el blog, cuando termine la beta abierta Cloudflare publicará una última versión mayor de Wrangler que te dirigirá a ti y a tu agente hacia cf, y Wrangler seguirá recibiendo mantenimiento durante 18 meses después del fin de la beta. La documentación también dice que no hace falta migrar un proyecto para empezar a usar cf: comandos de cuenta como cf d1 list funcionan en cualquier carpeta.

Las diferencias principales según la página oficial de comparación con Wrangler:

• La configuración vive en cloudflare.config.ts (con defineConfig, bindings.* y triggers.*) en lugar de wrangler.toml o wrangler.jsonc.
• El --env de Wrangler pasa a ser --mode.
• cf trabaja con IDs de recursos, no con nombres.
• cf usa datos remotos por defecto. --local solo funciona con KV, D1 y R2.
• cf dev, cf build y cf deploy delegan en el comando de tu framework, en el plugin de Vite de Cloudflare o en Wrangler 4.136.0 o posterior. Los proyectos nuevos usan Vite por defecto.

Requisitos antes de instalar Cloudflare CLI

La documentación pide Node.js 22.18 o posterior. Un detalle que vi: el campo engines del paquete npm de beta.26 es más estricto, ^22.23.0 || ^24.22.0 || ^26.12.0, así que lo más seguro es usar una versión reciente de Node 22, 24 o 26. Bun no sirve como entorno de ejecución: la documentación dice que los comandos que cargan cloudflare.config.ts fallan si cf se ejecuta con Bun.

La documentación oficial no indica qué sistemas operativos son compatibles, así que no voy a afirmar nada sobre eso. Tampoco encontré un precio propio para la CLI. Mi lectura es que la CLI no cuesta nada por sí misma y solo pagas los productos de Cloudflare que uses.

Paso 1: instalar Cloudflare CLI y comprobar la versión

npm install --global cf
cf --version

npm mostró added 32 packages in 3s y un aviso de que el script postinstall de workerd no estaba cubierto por su configuración de allowScripts. Ese aviso no afectó al resto de la prueba. La versión fue 1.0.0-beta.26. El paquete instala dos comandos, cf y cloudflare, que apuntan a la misma herramienta. Si quieres autocompletado, cf complete es compatible con zsh, bash, fish y PowerShell.

Paso 2: el aviso para agentes al principio de cf –help

Lo primero que imprime cf --help es un bloque dirigido a los agentes de IA. Les pide que no recorran páginas de --help anidadas y que usen la búsqueda. También les pide que las búsquedas sean anónimas, sin nombres, dominios, IDs ni tokens.

Mi lectura es que esto busca evitar que un agente ejecute --help en cientos de subcomandos y llene su contexto. Aquí la propia CLI le dice al agente cómo buscar.

Paso 3: cf cli search y cf docs search (sin iniciar sesión)

cf cli search recibe una tarea descrita en lenguaje normal y devuelve cinco comandos en JSON. No necesita credenciales.

Los otros dos comandos de consulta tampoco necesitan cuenta. cf schema muestra los detalles de la petición a la API que hay detrás de un comando (cambia el cf inicial de un resultado por cf schema). cf docs search "deploy a worker" devolvió cinco resultados en JSON ordenados, con título, descripción y URL. Uno era la página «Develop, build, and deploy» en developers.cloudflare.com/cf/projects/. Según la ayuda, el agente puede pedir la URL con Accept: text/markdown para leer la página completa.

Cuando ejecuté un comando real sin contexto, cf dns records list, terminó con código 1 y un mensaje claro: No zone specified, seguido de tres formas de indicar la zona (argumento posicional, --zone o CLOUDFLARE_ZONE_ID). Con un error así, a un agente le resulta fácil corregirse.

Paso 4: crear un Worker con cf init

cd ~
cf init ./hello --package-manager npm

Esto creó .gitignore, cloudflare.config.ts, package.json, src/index.ts, tsconfig.json y vite.config.ts, instaló las dependencias y generó los tipos en .cloudflare/types/index.d.ts. La configuración generada es esta:

import { bindings, defineConfig } from "cf/config";
import * as entrypoint from "./src/index.ts" with { type: "cf-worker" };

export default defineConfig({
	worker: {
		name: "hello",
		compatibilityDate: "2026-10-23",
		entrypoint,
		env: {
			WORLD: bindings.text("World"),
		},
	},
});

El Worker lee el binding con import { env } from "cloudflare:workers" y devuelve Hello ${env.WORLD}!. Los scripts de package.json son cf dev, cf build, cf deploy y, para typecheck, cf workers types && tsc.

Paso 5: cf dev y cf build

cf dev delegó en npx vite y sirvió el Worker en http://localhost:5173/. Un curl -i devolvió HTTP/1.1 200 OK, content-type: text/plain;charset=UTF-8 y Hello World!.

cf build delegó en npx vite build y dejó el resultado en .cloudflare/output/v0/workers/default/bundle/. El bundle ocupaba 0,24 kB.

Problema 1: cf dev –port no funciona con Vite

Primero ejecuté cf dev --port 8799 y obtuve este error:

Arguments cannot currently be forwarded to the detected dev command `npx
vite`. Run that command directly with the required arguments.

En beta.26 los argumentos no se pasan a Vite. Ejecuta cf dev sin argumentos, o lanza tú mismo npx vite --port 8799 si necesitas otro puerto.

Paso 6: iniciar sesión y desplegar (según la documentación, no lo ejecuté)

Me detuve antes de este paso porque necesita una cuenta de Cloudflare. Este es el orden que da la documentación para comprobar un proyecto antes del primer despliegue real:

cf build
cf deploy --dry-run
cf auth login
cf deploy

Según la documentación de CI, cf deploy --dry-run construye y valida el proyecto sin subir nada ni enviar peticiones a la API, así que no necesita credenciales. cf auth login muestra un enlace y un código de un solo uso y abre el navegador para que apruebes el acceso. En una máquina remota, por SSH o en un contenedor, añade --no-browser y aprueba desde otro dispositivo. Usa --force para volver a iniciar sesión y cf auth whoami para ver con qué cuenta estás conectado. Ten en cuenta que cf no reutiliza el inicio de sesión de Wrangler.

Desplegar un Worker con Claude Code y cf

La documentación tiene una página para agentes. La preparación tiene tres partes: instalar cf de forma global, iniciar sesión y añadir una línea a tu AGENTS.md o CLAUDE.md de usuario:

When interacting with Cloudflare, use the `cf` CLI unless the project has a
Wrangler configuration file.

Esa línea mantiene los proyectos de Wrangler con Wrangler y manda todo lo demás a cf. Claude Code lee CLAUDE.md y Codex lee AGENTS.md, así que la misma frase sirve para los dos. Si usas ambos, en mi comparación entre Codex CLI y Codex App explico dónde se ejecuta cada uno.

La documentación indica que el inicio de sesión en el navegador lo tienes que hacer tú, porque el agente no puede aprobarlo. Después basta con una instrucción como esta:

Create a Worker in ~/hello with cf init, run cf build and
cf deploy --dry-run, show me the output, and ask me before running cf deploy.

Mi lectura es que casi todo el mundo querrá confirmar antes del despliegue real. Es más fiable exigirlo con las reglas de permisos de Claude Code que confiar solo en la instrucción. Lo explico en Claude Code /permissions y blockWritesOutsideWorkingDirectories.

Tokens de API para agentes sin supervisión y CI

Un agente que funciona sin nadie delante no puede completar cf auth login. La documentación dice que hay que definir CLOUDFLARE_API_TOKEN y, en CI, también CLOUDFLARE_ACCOUNT_ID. Da al token solo los permisos que necesita la tarea y no subas al repositorio un archivo .env con tokens. cf elige las credenciales en este orden:

• CLOUDFLARE_API_TOKEN, incluido un valor cargado desde .env
• la opción --profile
• un perfil vinculado al proyecto con cf auth activate
• el perfil por defecto

La Global API Key no es compatible.

¿CLI o MCP?

cf está pensada para que el agente encuentre comandos mediante búsqueda, que es un enfoque distinto al de conectar herramientas por MCP. Si estás dudando entre los dos, mira Claude Code skills vs MCP y mi lista de los mejores MCP para Claude Code.

Paso 7: migrar un proyecto de Wrangler con cf migrate

Para probar la migración creé un repositorio Git pequeño con este wrangler.toml: una variable, un namespace de KV, un cron cada hora y un entorno staging.

name = "legacy-worker"
main = "src/index.js"
compatibility_date = "2025-06-01"
[vars]
GREETING = "hi"
[[kv_namespaces]]
binding = "CACHE"
id = "00000000000000000000000000000000"
[triggers]
crons = ["0 * * * *"]
[env.staging.vars]
GREETING = "staging"

cf migrate exige que el árbol de trabajo de Git esté limpio (--force lo evita). Empieza con --dry-run. La vista previa dijo que actualizaría cloudflare.config.ts, package.json y package-lock.json, que mantenía el empaquetador de Wrangler porque el plugin de Vite no estaba declarado (--bundler vite lo cambia) y que los entornos de Wrangler pasan a una sentencia switch (ctx.mode).

El cloudflare.config.ts generado usa defineConfig((ctx) => { switch (ctx.mode) { ... } }). El caso staging recibe el nombre de Worker legacy-worker-staging. El binding de KV CACHE solo aparece en el caso por defecto, lo que coincide con la regla de Wrangler de que los entornos no heredan los bindings de KV. El wrangler.toml original se queda donde estaba.

Problema 2: cf migrate –no-install deja una configuración que lanza un error

Con --no-install, el comando terminó con código 1 y el mensaje Migration requires follow-up work. Escribió cloudflare.config.ts pero no cambió package.json, y la configuración contiene un TODO y una línea que lanza Migration incomplete. Resolve every cf migrate TODO in cloudflare.config.ts. Instala cf@latest en el proyecto y elimina el TODO antes de ejecutar nada. Si no tienes un motivo concreto, deja que cf migrate instale las dependencias.

La documentación también advierte que no ejecutes cf dev, cf build ni cf deploy en un proyecto de Wrangler que todavía no hayas migrado. Las migraciones de Durable Objects, Workflows, Containers y los scripts de package pueden necesitar trabajo manual después.

Tareas que todavía necesitan Wrangler

cf sigue en beta y no lo cubre todo. La documentación indica dos huecos:

• Logs en directo: cf todavía no puede mostrar logs en tiempo real. Usa npx wrangler tail .
• Secrets individuales: cf todavía no puede definir un solo secret. Usa npx wrangler secret put --name , o pasa --secrets-file a cf deploy o a cf workers versions create.

Wrangler no lee cloudflare.config.ts, así que conserva el archivo de configuración de Wrangler mientras sigas usando comandos de Wrangler en un proyecto migrado.

Desactivar la telemetría

cf envía telemetría de uso anónima. Para desactivarla, define CF_SEND_TELEMETRY=false o DO_NOT_TRACK=1 en el entorno.

Preguntas frecuentes

¿Cuesta algo instalar Cloudflare CLI?

Se instala desde npm sin coste y no encontré un precio propio para la CLI. Mi lectura es que solo pagas los productos de Cloudflare que uses, igual que con Wrangler.

¿Tengo que dejar Wrangler ya?

No. Wrangler sigue funcionando y tendrá 18 meses de mantenimiento después del fin de la beta. Puedes usar cf para comandos de cuenta y de recursos sin migrar ningún proyecto.

¿Puedo instalar Cloudflare CLI en Windows, macOS y Linux?

La documentación oficial no indica qué sistemas operativos son compatibles. Yo solo lo probé en Linux.

¿Qué versión de Node.js necesito?

La documentación pide Node.js 22.18 o posterior. El paquete npm de beta.26 declara ^22.23.0 || ^24.22.0 || ^26.12.0.

¿Claude Code puede ejecutar cf auth login por mí?

No. La aprobación en el navegador la tienes que hacer tú. Para ejecuciones sin supervisión, usa un token de API como se explica arriba.

Fuentes

• Blog de Cloudflare: lanzamiento de cf (edición en español)
• Changelog de Cloudflare, 2026-09-28
• Documentación de cf (primeros pasos, agentes, CI, comparación y migración desde Wrangler)
• cloudflare/cf en GitHub