Cloudflare API desde la terminal: guía práctica de cf CLI

La ventaja práctica no está en escribir un comando más corto, sino en reducir el trabajo de integración. Quien dirige una startup puede revisar una cuenta sin recorrer todo el panel; un equipo de plataforma puede entregar resultados legibles por máquina a un agente; y una agencia puede estandarizar su trabajo en Cloudflare para varias cuentas de clientes sin mantener una capa de acceso a la API distinta para cada producto.

No hace falta comprar una licencia adicional para cf. El repositorio es de código abierto, un Worker pequeño puede comenzar en el plan Free de Cloudflare y Workers Paid tiene un mínimo mensual de $5. En el otro extremo del presupuesto, una plataforma general de gobernanza de infraestructura como Spacelift ofrece un nivel Starter+ de $20,000. cf elimina buena parte de las conexiones manuales con la API entre ambos extremos. No sustituye las aprobaciones, los registros de auditoría ni una gestión cuidadosa de permisos.

Cloudflare API desde cf CLI: qué es y cómo funciona

cf combina una superficie de comandos generada para toda la API de Cloudflare con flujos de proyecto creados a mano para tareas como crear, compilar, migrar y desplegar Workers. Wrangler se parece a un banco de trabajo especializado y bien equipado para Workers. cf añade el directorio y el mostrador de atención para todo el edificio de Cloudflare, pero sigue derivando algunos trabajos de Workers a Wrangler cuando continúa siendo la herramienta más fiable.

Esa diferencia también separa esta versión de la vista previa técnica que Cloudflare presentó el 13 de abril. La versión de abril solo cubría un pequeño grupo de productos. La beta abierta de septiembre es la que incorpora cobertura completa de la API, resultados JSON predeterminados, búsqueda de comandos, configuración de Workers en TypeScript y Vite como ruta predeterminada para Workers.

Hay cuatro cambios concretos en el flujo de trabajo:

• Toda la superficie de la API: los comandos generados siguen el patrón cf <product> [group…] <operation> para más de 3,000 operaciones.
• Búsqueda de comandos: cf cli search recibe una tarea escrita en lenguaje natural y devuelve cinco coincidencias ordenadas en JSON. No hace falta memorizar el árbol de comandos.
• JSON de forma predeterminada: los resultados estructurados de la API se envían a la salida estándar como JSON con formato legible, de modo que una persona, un script o un agente de programación pueden filtrar la misma respuesta.
• Configuración tipada de Workers: cloudflare.config.ts ofrece avisos de TypeScript a editores y agentes de programación. Por ahora, comienza con Workers. Llevar este modelo a toda una cuenta —DNS, zonas y políticas— es un objetivo futuro, no una función actual.

Cómo instalar cf CLI, autenticarte y comprobar una lectura

Empieza con una operación de solo lectura. Así puedes confirmar el paquete, la credencial, la selección de cuenta, el descubrimiento de comandos y el flujo de salida JSON antes de permitir que un script modifique algo.

El paquete oficial requiere Node.js 22 o una versión posterior. Para el uso interactivo en una terminal, cf auth login administra el perfil OAuth predeterminado. En CI, define un CLOUDFLARE_API_TOKEN con permisos limitados; cf comprueba esa variable de entorno antes que cualquier perfil OAuth guardado. También puedes crear perfiles con nombre y asociarlos a directorios distintos cuando trabajas con cuentas de clientes o empresas diferentes.

La consulta que envíes a cf cli search debe ser genérica. Describe la acción y el tipo de recurso, pero no incluyas dominios, direcciones de correo, identificadores de cuenta ni tokens.

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"))'

En este momento, la búsqueda coloca cf zones list en primer lugar para esa tarea. La última línea sirve como prueba: hace una llamada de solo lectura a la API y solo termina correctamente si el resultado es una lista JSON cuyas entradas contienen name y status. Si administras varias cuentas, selecciona un perfil con nombre mediante --profile o filtra el comando con --account-id.

No pegues un token en el historial del shell. Coloca un token con alcance limitado en el entorno del proceso que usa CI y concédele únicamente los permisos de lectura o escritura que necesite el trabajo. Para una sesión individual en terminal, OAuth es la opción más cómoda porque cf puede renovar el perfil seleccionado.

Qué demostró la prueba en un entorno temporal

Una instalación nueva y aislada realizada el 29 de septiembre devolvió cf v1.0.0-beta.5. La búsqueda de comandos produjo una lista JSON válida de cinco elementos, cf init creó un proyecto Worker tipado y tanto el proyecto nuevo como un entorno Vite migrado compilaron en local. El entorno no incluía credenciales para una cuenta de prueba de Cloudflare, por lo que la lectura autenticada de zonas y el despliegue no figuran como pruebas completadas.

Ese límite es importante. Una compilación local correcta valida la ruta del proyecto. No demuestra que el token tenga los permisos de producción adecuados ni que un despliegue haya llegado a Cloudflare.

Crea un Worker pequeño y revisa lo que generó cf

cf init es la prueba limpia más rápida del nuevo flujo de proyectos. En un directorio vacío crea código TypeScript, cloudflare.config.ts, vite.config.ts, scripts de paquete y tipos generados para Workers. Después, cf build delega la compilación en Cloudflare Vite Plugin y produce un Build Output estandarizado.

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

Abre cloudflare.config.ts después de cualquiera de las dos rutas. En un Worker básico deberías encontrar un bloque worker con su nombre, fecha de compatibilidad, punto de entrada y bindings tipados. Un binding de texto se declara mediante la API de configuración, en lugar de copiarlo entre varios bloques de entorno. Ahí es donde TypeScript resulta útil: un campo mal escrito puede convertirse en una advertencia del editor antes de provocar un despliegue fallido.

La configuración generada de Vite no es decorativa. Vite es ahora la ruta predeterminada de desarrollo local y compilación en cf, y Cloudflare recomienda su plugin de Vite tanto para frontends como para APIs de backend. En el proyecto temporal, npm run build delegó el trabajo en Vite y terminó correctamente. El despliegue se dejó fuera de forma deliberada. Cuando completes la revisión y la prueba de cuenta, el comando documentado cf deploy compila y sube el proyecto de forma predeterminada.

Cuándo sigue haciendo falta Cloudflare Wrangler

No elimines Wrangler solo porque cf se instaló correctamente. La decisión de migrar depende de la ruta de compilación del proyecto.

En un Worker existente basado en Vite, cf migrate puede convertir la configuración JSON, JSONC o TOML de Wrangler en cloudflare.config.ts. El comando detecta Cloudflare Vite Plugin junto a la configuración de Wrangler y elige la ruta de Vite. Si el plugin no está declarado, las versiones beta actuales seleccionan el empaquetador de Wrangler. Ejecuta primero la vista previa, revisa cada tarea pendiente y migra una copia o una rama limpia antes de tocar el proyecto de trabajo.

En Workers de JavaScript que aún dependen del comportamiento de esbuild de Wrangler, cf delega en Wrangler el desarrollo y el despliegue. Hace lo mismo con Workers de Rust y Python. Es una medida de compatibilidad, no una migración fallida. El equipo adopta cf como puerta de entrada mientras conserva en el flujo la herramienta de compilación que ya ha demostrado ser fiable.

El calendario de soporte de Cloudflare también se presta a confusión. El mantenimiento de Wrangler está previsto durante 18 meses después de que termine la beta abierta, no durante 18 meses desde el lanzamiento del 28 de septiembre. No hay motivo para forzar esta semana la conversión a Vite de un proyecto en Rust, Python o esbuild.

Siete flujos de trabajo que generan valor desde el principio

Los mejores primeros casos de uso comparten una característica: eliminan búsquedas y tareas de formato repetitivas sin conceder permisos amplios de escritura desde el primer día.

1. Una agencia estandariza las revisiones de cuentas

Una agencia puede vincular un perfil OAuth con nombre a cada directorio de cliente, buscar el comando de lectura necesario y enviar siempre la misma estructura JSON a un script de revisión. Así se reduce la disparidad que aparece cuando una persona recorre paneles mientras otra mantiene un comando personalizado con curl. El beneficio es la repetibilidad entre clientes, sobre todo en revisiones de DNS, zonas, ajustes de cuenta y seguridad.

2. Un equipo de plataforma ofrece a sus agentes una interfaz segura para Cloudflare

Un responsable de plataforma puede definir en AGENTS.md una regla para cf cli search, autorizar los comandos de lectura de forma predeterminada y exigir aprobación humana para cualquier cambio. La búsqueda evita que el agente adivine sintaxis antigua de Wrangler, mientras que JSON mantiene la salida compacta y fácil de filtrar. Es especialmente útil si el equipo ya recurre a agentes para revisar estados de compilación, registros, colas o recursos de cuenta y quiere una interfaz única y predecible.

3. El equipo de guardia reúne contexto durante un incidente

Durante un incidente, la persona responsable puede buscar la lectura adecuada de registros, zonas, conjuntos de reglas o analítica en vez de recorrer varios paneles de producto. El comando exacto sigue siendo importante y los permisos continúan aplicándose, pero el descubrimiento ocurre en local y la respuesta queda lista para jq. En equipos que ejecutan tareas como Cloudflare Browser Run, esto acorta el camino entre un trabajo fallido y el estado relacionado de la cuenta.

4. Quien funda una startup crea un Worker sin diseñar toda la cadena de herramientas

Quien esté creando un webhook, un servicio de redirección o una API interna pequeña puede ejecutar cf init, revisar el Worker y el binding generados y después compilar con Vite sin seleccionar cada paquete por separado. El proyecto puede comenzar en Workers Free. Si necesita el plan de pago, el mínimo actual es de $5 por cuenta al mes. El beneficio es una ruta corta hasta un artefacto local listo para revisión, no la promesa de que operar en producción será gratis.

5. Un equipo de Vite convierte su configuración sin reescribir la aplicación

Un equipo de ingeniería que ya utiliza un Worker basado en Vite puede ejecutar cf migrate --dry-run sobre una copia, revisar el TypeScript generado y compilar antes de modificar el despliegue. Resulta especialmente útil cuando los bloques de entorno se han vuelto repetitivos. El nuevo formato puede calcular la configuración a partir de una base común, pero el equipo debe migrar el comportamiento y no limitarse a cambiar la sintaxis del archivo.

6. Un equipo de datos u operaciones incorpora lecturas de Cloudflare a sus informes

Como los resultados estructurados son JSON de forma predeterminada, una lectura puede enviarse a jq, a un cargador para el almacén de datos o a un informe programado sin extraer datos de una tabla Unicode. El beneficio para el negocio es deliberadamente poco llamativo: menos adaptadores de salida y menos reglas de análisis frágiles. Usa un token de lectura con alcance limitado y evita que la salida del comando aparezca en registros públicos de CI.

7. Un equipo de Workers revisa recursos locales antes de tocar producción

Los comandos compatibles aceptan --local y se comunican con una instancia efímera de Miniflare que utiliza estado local. Esto incluye operaciones definidas para KV, D1 y R2. Si no existe un equivalente local, cf devuelve un error en vez de ejecutar la operación en producción sin avisar. Un equipo que desarrolle un Worker de Cloudflare AI Search puede usar ese límite para probar datos locales auxiliares sin convertir un comando de desarrollo en una escritura remota.

Dos productos que vale la pena construir alrededor de cf

La oportunidad de producto no está en la propia CLI, sino en la capa de control que los equipos todavía necesitan alrededor de una superficie de API tan amplia.

Mejor oportunidad: control de cambios de Cloudflare para agencias

Construye una capa específica de aprobación y evidencias para agencias o equipos pequeños de plataforma que administran varias cuentas de Cloudflare. Una persona propone un cambio en DNS, una zona, WAF o un Worker; el producto utiliza cf para obtener el estado JSON actual, muestra un diff fácil de entender, solicita aprobación, ejecuta con un perfil de alcance limitado y guarda el resultado.

La señal de demanda es modesta, pero comercial: cloudflare dns management recibe unas 170 búsquedas mensuales en EE. UU., tiene un CPC de $6 y muestra pujas en la parte superior de la página de entre $3.85 y $36.64. La gobernanza general de infraestructura también maneja presupuestos reales. Spacelift ofrece Starter+ por $20,000. Un producto específico para Cloudflare puede ser más barato y fácil de adoptar porque no necesita gobernar todas las nubes.

La versión vendible más pequeña es una aplicación de GitHub o una cola de revisión alojada para cambios en DNS y Workers, con aislamiento de perfiles, una lista de comandos permitidos, JSON anterior y posterior y reversión con un clic cuando la API subyacente la admita. El reto está en la ventaja defensible: cf ya aporta la cobertura de comandos, así que el trabajo difícil está en las políticas, las evidencias, los permisos y el flujo de las agencias. Una simple interfaz gráfica sobre cf se copiará con rapidez.

Función útil: análisis de preparación para migrar Workers

Construye un analizador que clasifique un repositorio como Vite nativo, esbuild mediante Wrangler, Python o Rust; después, que ejecute la vista previa segura de la migración y convierta las tareas pendientes en un checklist para el pull request. Los compradores son equipos con una cartera de Workers, no una persona que migra un único proyecto pequeño.

La demanda es demasiado reducida para sostener por sí sola una empresa. cloudflare worker deployment recibe unas 10 búsquedas mensuales en EE. UU., aunque la consulta tiene intención transaccional. El MVP razonable es una función de pago dentro de un producto de operaciones para Cloudflare o de un servicio de migración: análisis del repositorio, cf migrate --dry-run, verificación de la compilación y un informe claro sobre la alternativa de Wrangler. El riesgo es el ritmo de cambios durante la beta. El analizador debe seguir de cerca las versiones de cf y Cloudflare Vite Plugin o sus recomendaciones envejecerán más rápido que los proyectos que evalúa.

Límites de cf CLI y una decisión realista

Usa cf desde ahora para descubrir comandos, hacer lecturas de cuenta basadas en JSON, crear Workers nuevos con Vite y ensayar migraciones con cuidado. Conserva Wrangler donde cf delegue en él y mantén las escrituras en producción detrás de permisos explícitos y una revisión.

La beta abierta todavía no convierte cloudflare.config.ts en una fuente de verdad para toda la cuenta. Comienza con Workers. Tampoco transforma cada operación de la API de Cloudflare en un flujo de negocio seguro. Una cobertura completa de la API amplía lo que puede alcanzar un token; por eso el privilegio mínimo y la revisión de comandos son más importantes, no menos.

La opción local tiene límites intencionales. Las operaciones compatibles de KV, D1, R2, Durable Object y Workflow pueden utilizar estado local, pero una operación sin equivalente en el explorador local devuelve un error. Es una buena propiedad de seguridad, aunque también significa que --local no es un espejo sin conexión universal de Cloudflare.

Por último, las versiones beta cambian con rapidez. Fija la versión de cf en las dependencias del proyecto cuando trabaje un equipo, revisa la configuración generada y haz que CI utilice la versión local del proyecto. Una instalación global resulta cómoda para descubrir comandos; una versión fijada permite que todo el equipo obtenga el mismo comportamiento.

Si quieres diseñar y construir una ruta segura de automatización de Cloudflare para tu equipo, consulta sistemas de IA en producción.