El día a día con Wrangler

Crear, configurar y desplegar son actos puntuales; operar es lo que haces todos los días. Y ahí Wrangler deja de parecer un empaquetador para revelarse como lo que de verdad es: la consola de operaciones de toda la plataforma. Con el mismo CLI autenticado ves los logs de producción en vivo, guardas una credencial cifrada, creas una base de datos, escribes una clave en un almacén global y regeneras los tipos de tu código. Dominar este puñado de comandos es la diferencia entre desplegar un Worker y gobernar un sistema en el edge.

🎯 Al terminar esta lección sabrás

Observar producción en vivo con wrangler tail y filtrar el ruido.
Gestionar credenciales cifradas con wrangler secret put y distinguirlas de vars.
Manejar los almacenes con los subcomandos de d1, kv y r2.
Generar el tipo Env desde tus bindings con wrangler types.

Ver qué pasa: `wrangler tail`

Un Worker corre lejos, en cientos de ubicaciones, así que “meter un print y mirar la terminal” no sirve. wrangler tail resuelve eso: abre un stream en vivo de los logs de tu Worker en producción, con cada petición, cada excepción y cada console.log llegando en tiempo real. Como el volumen puede ser enorme, viene con filtros para quedarte solo con lo que importa.

# stream de logs de produccion en vivo
wrangler tail

# solo peticiones con error, en JSON para procesarlas
wrangler tail --status error --format json

# acotar por metodo y por un texto concreto en el log
wrangler tail --method POST --search "timeout"

El formato pretty es para leer con los ojos; json es para tuberías y herramientas. Los filtros —--status, --method, --search, --ip— se combinan para aislar un problema entre miles de peticiones, y en Workers con mucho tráfico un muestreo evita que el propio tail te ahogue. Junto a la observabilidad persistente (Workers Logs), tail es tu ventana inmediata cuando algo arde y necesitas verlo ahora.

Secretos: `wrangler secret put`

Hay configuración que puede vivir a la vista —una URL, un nombre de entorno— y configuración que jamás: tokens, claves de API, credenciales. Para lo primero están las vars del manifiesto, en texto plano. Para lo segundo está wrangler secret put, que cifra el valor y lo guarda fuera del manifiesto; luego llega a tu código por env, indistinguible de una variable normal en el punto de uso pero nunca escrito en un archivo versionado.

# guarda un secreto cifrado (pide el valor de forma segura)
wrangler secret put API_TOKEN

# cargar varios de golpe desde un archivo JSON
wrangler secret bulk ./secrets.json

# listar los nombres (nunca los valores) y borrar uno
wrangler secret list
wrangler secret delete API_TOKEN

Los secretos, como los bindings, son por entorno: wrangler secret put API_TOKEN --env staging guarda uno solo para staging. Es coherente con el modelo del manifiesto —cada entorno con nombre es un Worker aparte— y es justo lo que impide que una credencial de producción se cuele en un despliegue de pruebas.

💡

`vars` para lo que puede verse, `secret` para lo que no

La regla es de higiene, no de gusto. Una var vive en wrangler.jsonc, que está en git: perfecta para valores que no te importa que cualquiera lea. Un secreto se cifra y jamás toca el repositorio: obligatorio para todo lo que concede acceso. Ambos aterrizan en env con la misma forma, así que tu código no distingue uno de otro —la diferencia está en dónde reposa el valor cuando no se está usando—. Si dudas de si algo es un secreto, trátalo como tal.

Los almacenes: `d1`, `kv` y `r2`

Cada producto de almacenamiento tiene su familia de subcomandos, y todos comparten una gramática deliberadamente uniforme: verbos como create, list, get, put y delete que significan lo mismo en todas partes. Aprendes el patrón una vez y lo reutilizas en cada almacén.

# D1: crear la base, versionar y aplicar migraciones, ejecutar SQL
wrangler d1 create app
wrangler d1 migrations create app crear_tabla_users
wrangler d1 migrations apply app --remote
wrangler d1 execute app --remote --command "SELECT count(*) FROM users;"

# KV: crear un namespace, escribir, leer y listar claves
wrangler kv namespace create CACHE
wrangler kv key put --binding CACHE saludo "hola" --remote
wrangler kv key list --binding CACHE --remote

# R2: crear un bucket, subir y recuperar un objeto
wrangler r2 bucket create uploads
wrangler r2 object put uploads/logo.png --file ./logo.png
wrangler r2 object get uploads/logo.png --file ./copia.png

El flujo de D1 merece atención: migrations create genera un archivo SQL versionado, y migrations apply lo ejecuta llevando la cuenta de cuáles ya corrieron, de modo que el esquema evoluciona de forma reproducible en vez de a golpe de comandos sueltos. Igual que en wrangler dev, estos subcomandos distinguen el almacén local del remoto con --local y --remote: es la misma frontera de la lección anterior, ahora en la línea de comandos.

📝

Del `kv:namespace` con dos puntos al `kv namespace` con espacios

Un detalle de historia que muerde al copiar comandos viejos: las versiones antiguas de Wrangler usaban dos puntos como separador —kv:namespace, kv:key—, y el Wrangler de 2026 usa espacios —kv namespace, kv key—. Un tutorial desactualizado o una respuesta antigua te dará la forma con dos puntos, que hoy falla. Ante un error de sintaxis en un subcomando de almacenamiento, sospecha primero de los dos puntos.

Tipos desde la infraestructura: `wrangler types`

El último comando cierra el círculo entre lo que declaras y lo que tu código cree. wrangler types lee los bindings de tu manifiesto y genera worker-configuration.d.ts con una interfaz Env tipada: si declaraste un binding DB de D1, env.DB aparece con su tipo correcto y tu editor lo autocompleta. Además usa la compatibility_date y los flags para elegir la versión adecuada de los tipos del runtime, de modo que las Web APIs disponibles coinciden con las que realmente tendrás.

# genera worker-configuration.d.ts desde tus bindings
wrangler types

flowchart LR
A[Bindings en wrangler.jsonc] --> B[wrangler types]
B --> C[worker-configuration.d.ts]
C --> D[Interface Env tipada]
D --> E[Autocompletado y errores en compilacion]

Ese archivo generado aporta a la vez la interfaz Env y los tipos del runtime, así que ya no hace falta instalar y mantener a mano un paquete de tipos aparte; basta con referenciarlo desde tu tsconfig.json. Por eso C3 deja un script cf-typegen: cada vez que añades un binding, regeneras los tipos y tu código se entera. No escribes el tipo Env a mano; lo deriva la herramienta desde la verdad del manifiesto.

📡

tail

Logs de producción en vivo. Filtra por estado, método o texto y elige formato legible o JSON.

🔐

secret

Credenciales cifradas fuera del manifiesto. put, bulk, list, delete; llegan por env.

🗄️

d1 · kv · r2

Gestión de los almacenes con verbos uniformes y la frontera --local frente a --remote.

🏷️

types

Genera el tipo Env desde tus bindings. Tu infraestructura, convertida en tipos.

⚡

Un solo CLI, una sola gramática, toda la plataforma

Lo revelador de los comandos del día a día no es cada uno por separado, sino que existan todos bajo el mismo techo. Cloudflare es una plataforma heterogénea —compute, logs, secretos, una base SQL, un almacén clave-valor, objetos estilo S3, IA— y, sin embargo, la operas entera con un único CLI autenticado y una gramática consistente: los mismos verbos create, list, get, put y delete reaparecen en cada producto, así que el coste de aprender el siguiente almacén es casi cero. Esa coherencia no es cosmética: es lo que permite que operar sea código —un script, un paso de CI, un runbook reproducible— en vez de una serie de clics irrepetibles en un panel. Y wrangler types es la culminación del principio que atraviesa todo el nivel: la infraestructura y el código no son dos mundos que sincronizas a mano, sino dos vistas de una misma verdad que fluye del manifiesto hacia los tipos. Cuando lo interiorizas, dejas de ver Wrangler como la herramienta con la que despliegas y empiezas a verlo como la consola desde la que gobiernas el sistema entero: observas, aseguras, persistes y tipas, todo con el mismo vocabulario. Esa es la diferencia entre saber usar Workers y saber operarlos.

⚔️ Un turno de operaciones

Con un Worker desplegado, abre wrangler tail, provoca una petición con error y localízala filtrando con --status error.
Guarda un secreto API_TOKEN con wrangler secret put, confírmalo en wrangler secret list y léelo desde el handler vía env.API_TOKEN.
Crea una base D1, genera una migración con wrangler d1 migrations create, aplícala con --remote y ejecuta un SELECT.
Crea un namespace de KV, escribe y lee una clave con --remote, y repite con --local para notar que son almacenes distintos.
Añade un binding nuevo al manifiesto, ejecuta wrangler types y verifica que env refleja el binding con autocompletado en tu editor.

Ver qué pasa: wrangler tail

Secretos: wrangler secret put

Los almacenes: d1, kv y r2

Tipos desde la infraestructura: wrangler types