<zone> is the domain or the zone id. Reads accept --json; changes take --reason, --dry-run and --yes (global options).
Read
zones list
zones list [--merged]The organisation's zones with their status, DNS mode and current version. A zone or client token sees only its own.
| Option | Meaning |
|---|---|
--merged | Include zones merged into another (hidden by default). |
zones show
zones show <zone>The zone, its current version and its edge settings. For an external zone it also shows the ownership TXT record to publish, the CNAME target (edge.openwaf.dev) and the edge addresses for records at the apex.
zones hosts
zones hosts <zone>External zones only: whether each proxied name already points at OpenWAF in the public DNS (by CNAME or A/AAAA). Answers are cached for about a minute.
zones check
zones check <zone>Checks now the delegation of a delegated zone (its name servers at the registrar), or the ownership TXT record of an external zone, and activates the zone when it is verified. It prints the result and what each public resolver answered. Needs the Tech role; takes no reason because it changes no configuration.
zones effective
zones effective <zone> <name>The configuration one name gets at the edge: the zone's settings merged with the name's own, its origin, the rules that apply to it, its rate limiting rules and its redirects.
zones history
zones history <zone> [<version>] [--limit N] [--before V]Without <version>: the zone's versions, newest first, with date, actor, action and reason (a revert shows [revierte a N]). With <version>: that version's details and its full snapshot. Works with the id of a deleted zone. See View history.
| Option | Meaning |
|---|---|
--limit N | At most N versions (API default 50, maximum 500). |
--before V | Only versions older than V. |
zones diff
zones diff <zone> <from> [<to>]What changed from version <from> to <to> (default: the current version), one line per change.
zones propagation
zones propagation <zone>The desired version and, for each edge node that serves the zone, its status, applied version, pending time, lag and last poll. See Propagation to the edge.
Change
zones add
zones add <name> [--mode delegated|external] --reason "…"Adds a zone (version 1).
| Option | Meaning |
|---|---|
--mode delegated | Default. OpenWAF serves the zone's DNS once you delegate it to the name servers shown by zones show. |
--mode external | Your DNS stays where it is. The zone activates when you publish its ownership TXT record (see zones show), and you point each proxied name at the edge yourself. |
zones set
zones set <zone> key=value … --reason "…" [--wait]
zones set <zone> --host <name> key=value … [--unset <key>]… --reason "…" [--wait]Changes the zone's edge settings with key=value arguments. With --host, it changes the settings of one name of the zone, which override the zone's for that name.
| Option | Meaning |
|---|---|
--host <name> | Change the settings of this name (full name) instead of the zone's. |
--unset <key> | With --host: the name stops overriding this key and inherits it from the zone again. Repeatable. |
--wait[=120s] | Wait for propagation. |
Some examples, by area:
| Area | Example |
|---|---|
| WAF | waf_level=high, mode=active |
| HSTS | hsts.max_age=31536000 |
| Origin | origin.port=8443 (with --host), origin.tls_verify=full_strict, origin.server_name=origin.example.com, origin.client_cert:=true |
| Cache | cache.enabled:=true, cache.query.mode=ignore, cache.rules:='[…]' |
| 103 Early Hints | early_hints.enabled:=true, early_hints.mode=html_head, early_hints.extra_origins:='["https://cdn.example.com"]' |
| Real user monitoring | rum.enabled=true, rum.sample_rate=0.25, rum.exclude_paths=/admin,/wp-login.php |
| AI agents | ai_agents.enabled=true, ai_agents.mode=log or enforce, ai_agents.template=search_ok_block_training, verified_only or block_unverified_automation, ai_agents.policy.ai_training=block, ai_agents.bot_overrides=gptbot:block,ccbot:allow, ai_agents.trap.enabled=true, ai_agents.endpoints:='[…]' |
| Redirects | redirects:='[…]' (replaces the whole list) |
| Rate limiting | rate_rules:='[…]' (replaces the whole list; ratelimit edits one rule at a time) |
With --host, a name's early_hints, ai_agents and rate_rules replace the zone's as a whole. The full list of settings and their values is in the API reference.
openwaf-cloud ctl zones set example.com waf_level=high --reason "Raise WAF level" --wait
openwaf-cloud ctl zones set example.com --host api.example.com origin.port=8443 --reason "API origin port"
openwaf-cloud ctl zones set example.com --host api.example.com --unset origin.port --reason "Back to the zone's port"zones revert
zones revert <zone> <version> --reason "…" [--allow-missing-certs] [--wait]Restores the configuration of <version> as a new version. See Revert a zone.
| Option | Meaning |
|---|---|
--allow-missing-certs | Apply even if some site would be left without a valid certificate. |
--wait[=120s] | Wait for propagation. |
zones set-client
zones set-client <zone> <client|-> --reason "…" [--wait]Assigns the zone to an end client (by name or id), or with - removes the assignment. Needs an organisation-wide credential.
zones merge
zones merge <child> --into <parent> --reason "…"Merges a zone into another: the child's names, records and settings move to the parent. The simulation shows, name by name, that the configuration served stays equivalent, and the merge is applied only if it does. The child becomes read-only and is kept for 14 days so the merge can be undone. Needs an organisation admin.
zones unmerge
zones unmerge <child> --reason "…"Undoes a merge while the parent has not changed since: both zones return to their versions from before the merge. Needs an organisation admin.
zones rm
zones rm <zone> --reason "…"Deletes the zone with its records, settings and rules; OpenWAF stops serving its DNS and sites. Its history is kept, ending with a zone.delete version.