# zones

> Every openwaf-cloud ctl zones command: list, show, add, configure edge settings, check delegation, history, diff, revert, propagation, merge and delete.

`<zone>` is the domain or the zone id. Reads accept `--json`; changes take `--reason`, `--dry-run` and `--yes` ([global options](https://developers.openwaf.dev/cli/reference/options/)).

## Read

### zones list

```text
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

```text
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

```text
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

```text
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

```text
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

```text
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](https://developers.openwaf.dev/change-control/view-history/).

| Option | Meaning |
|---|---|
| `--limit N` | At most N versions (API default 50, maximum 500). |
| `--before V` | Only versions older than V. |

### zones diff

```text
zones diff <zone> <from> [<to>]
```

What changed from version `<from>` to `<to>` (default: the current version), one line per change.

### zones propagation

```text
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](https://developers.openwaf.dev/change-control/propagation/).

## Change

### zones add

```text
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

```text
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](https://developers.openwaf.dev/cli/output-and-exit-codes/#key-value). 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`](https://developers.openwaf.dev/cli/reference/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](https://developers.openwaf.dev/api/).

```sh
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

```text
zones revert <zone> <version> --reason "…" [--allow-missing-certs] [--wait]
```

Restores the configuration of `<version>` as a new version. See [Revert a zone](https://developers.openwaf.dev/change-control/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

```text
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

```text
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

```text
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

```text
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.