Every command that changes something follows the same flow, the one described in Simulate, then confirm:
- It reads the zone's current version.
- It asks the API for a simulation of the change with that version and prints the plan:
Simulación sobre zona example.com: versión 7 → 8followed by one line per change and any warnings (aviso:). - If the change would modify nothing, it prints
Sin cambios: no hay nada que aplicar.("no changes: nothing to apply") and stops with exit code 0. - It asks
¿Aplicar? [s/N]("apply?").s,sí,yoryesapply; anything else cancels. - It sends the change with the same expected version and prints
Aplicado: zona example.com, versión 8.("applied"). - With
--wait, it follows propagation until every edge node has the new version.
If the zone changed between steps 1 and 5, the API refuses the change, nothing is applied and the CLI exits with code 3.
Diff lines
| Line | Meaning |
|---|---|
+ path: value | Added. |
- path: value | Removed. |
~ path: before → after | Replaced. |
Long values are cut at 160 characters. Certificate changes are listed apart under Certificados (informativo…): their material is not versioned and a revert does not restore them.
Options of every change
| Option | Meaning |
|---|---|
--reason "…" | Required. 1–500 characters, no line breaks. Stored in the version and in the audit log. |
--dry-run | Only simulate, with the same validation as the real change. Nothing is applied. |
--yes | Apply without asking. Required when standard input is not a terminal (CI, cron, pipes); without it the CLI stops with sin terminal para confirmar and applies nothing. |
--wait[=120s] | After applying, wait until every edge node has applied the new version. --wait waits up to 120 seconds; --wait=90s or --wait=90 sets another limit. Available on zone changes. |
Waiting for the edge
With --wait, the CLI prints Esperando a que los nodos apliquen la versión 8 (plazo 2m0s)… and then one line per node as it confirms (aplicado … en 41.3s). It ends with Propagado a N nodos en … ("propagated to N nodes in …").
Each node applies a change within one polling interval and confirms it on its next poll, so the time measured is about twice the interval. If some node has not confirmed in time, the CLI lists the pending ones and exits with code 4; the change stays applied. Temporary API errors while waiting are retried until the time is up.
Changes that are not zone versions
| Commands | Simulation | --wait |
|---|---|---|
cache purge, origin-certs create, origin-certs revoke | Simulated by the API; not versioned. | No |
zones merge, zones unmerge | Simulated; they create versions in both zones. | No |
zones add, zones rm | Simulated; versioned. | No |
clients add/set/rm, brand set, whitelabel domain, whitelabel nameservers | Not simulated: --dry-run prints what would be sent and sends nothing. | No |
Scripts and CI
openwaf-cloud ctl records set example.com www/A content=203.0.113.20 \
--reason "Deploy 42: move www" --yes --wait=180s
case $? in
0) echo "applied and propagated" ;;
3) echo "someone changed the zone: review and retry" ;;
4) echo "applied, but some edge node is late" ;;
*) exit 1 ;;
esacUse a token with the narrowest scope that works, such as one limited to the zone.