# Cambios: simulación y confirmación

> Cómo cada cambio de la CLI se simula, se enseña como diferencias, se confirma contra la versión de la zona y, si quieres, se sigue hasta el borde.

Toda orden que cambia algo sigue el mismo camino, el que describe [Simular y después confirmar](https://developers.openwaf.dev/es/change-control/simulate-and-confirm/):

1. Lee la versión actual de la zona.
2. Pide a la API una **simulación** del cambio con esa versión e imprime el plan: `Simulación sobre zona example.com: versión 7 → 8`, una línea por cambio y los avisos (`aviso:`).
3. Si el cambio no modificaría nada, imprime `Sin cambios: no hay nada que aplicar.` y termina con el código 0.
4. Pregunta `¿Aplicar? [s/N]`. `s`, `sí`, `y` o `yes` aplican; cualquier otra respuesta cancela.
5. Envía el cambio con **la misma** versión esperada e imprime `Aplicado: zona example.com, versión 8.`
6. Con `--wait`, sigue la propagación hasta que todos los nodos de borde tienen la versión nueva.


Si la zona cambia entre los pasos 1 y 5, la API rechaza el cambio, no se aplica nada y la CLI sale con el código 3.

## Líneas de diferencias

| Línea | Significado |
|---|---|
| `+ ruta: valor` | Añadido. |
| `- ruta: valor` | Quitado. |
| `~ ruta: antes → después` | Cambiado. |

Los valores largos se cortan a 160 caracteres. Los cambios de certificados se listan aparte, bajo `Certificados (informativo…)`: su material no se versiona y volver atrás no los restaura.

## Opciones de todo cambio

| Opción | Significado |
|---|---|
| `--reason "…"` | **Obligatoria.** De 1 a 500 caracteres, sin saltos de línea. Se guarda en la versión y en la auditoría. |
| `--dry-run` | Solo simular, con la misma validación que el cambio real. No se aplica nada. |
| `--yes` | Aplicar sin preguntar. Obligatoria cuando la entrada estándar no es un terminal (CI, cron, tuberías); sin ella la CLI se detiene con `sin terminal para confirmar` y no aplica nada. |
| `--wait[=120s]` | Tras aplicar, esperar a que todos los nodos de borde apliquen la versión nueva. `--wait` espera hasta 120 segundos; `--wait=90s` o `--wait=90` fija otro plazo. Disponible en los cambios de zona. |

## Esperar al borde

Con `--wait`, la CLI imprime `Esperando a que los nodos apliquen la versión 8 (plazo 2m0s)…` y después una línea por nodo a medida que confirma (`aplicado … en 41.3s`). Termina con `Propagado a N nodos en …`.

Cada nodo aplica un cambio en un intervalo de consulta y lo confirma en la siguiente consulta, así que el tiempo medido ronda el doble del intervalo. Si algún nodo no ha confirmado a tiempo, la CLI enumera los pendientes y sale con el código 4; el cambio sigue aplicado. Los errores pasajeros de la API durante la espera se reintentan hasta el plazo.

## Cambios que no son versiones de zona

| Órdenes | Simulación | `--wait` |
|---|---|---|
| `cache purge`, `origin-certs create`, `origin-certs revoke` | Las simula la API; no se versionan. | No |
| `zones merge`, `zones unmerge` | Se simulan; crean versiones en las dos zonas. | No |
| `zones add`, `zones rm` | Se simulan; se versionan. | No |
| `clients add/set/rm`, `brand set`, `whitelabel domain`, `whitelabel nameservers` | No se simulan: `--dry-run` imprime lo que enviaría y no envía nada. | No |

## Scripts y CI

```sh
openwaf-cloud ctl records set example.com www/A content=203.0.113.20 \
  --reason "Despliegue 42: mover www" --yes --wait=180s
case $? in
  0) echo "aplicado y propagado" ;;
  3) echo "alguien ha cambiado la zona: revisa y repite" ;;
  4) echo "aplicado, pero algún nodo de borde va con retraso" ;;
  *) exit 1 ;;
esac
```

Usa el token con el alcance más estrecho que funcione, por ejemplo uno limitado a la zona.