Get the CLI
openwaf-cloud is a single binary. OpenWAF does not publish downloadable builds of it yet; if you want to use it, ask [email protected]. Everything it does is also available from the dashboard, the API, the SDKs and the MCP server.
Check that it runs:
openwaf-cloud ctl helpPoint it at the API
Set the API address once in your shell profile. The CLI adds the /v1/… paths itself, so give it the host only:
export OPENWAF_API_URL=https://dash.openwaf.devGive it a token
Create an API token in the dashboard under API tokens with the role and scope you need: Read only is enough to look around, Tech to make changes. Tokens start with owf_.
The CLI never takes the token as an argument, so it does not end up in your shell history or the process list. Use one of:
Save the token in a file only you can read. The file may hold the bare token, or a single line NAME_TOKEN=value, so a .env-style file works too.
mkdir -p ~/.config/openwaf
read -rs TOKEN && printf '%s\n' "$TOKEN" > ~/.config/openwaf/token && unset TOKEN
chmod 600 ~/.config/openwaf/token
export OPENWAF_TOKEN_FILE=~/.config/openwaf/tokenThe CLI refuses a file that is not yours or that the group or others can read.
read -rs OPENWAF_TOKEN && export OPENWAF_TOKENUseful in CI, where the token comes from the pipeline's secret store.
Set only one of OPENWAF_TOKEN and OPENWAF_TOKEN_FILE; with both, the CLI stops.
Choose the organisation
A token belongs to one organisation, and the CLI uses it by default. To be explicit, set OPENWAF_ORG (or --org) to the organisation's name or id:
export OPENWAF_ORG=acmeFirst read
openwaf-cloud ctl zones list
openwaf-cloud ctl zones show example.com
openwaf-cloud ctl records list example.comZones are named by domain or id. Add --json to any read to get the API's answer as is.
First change
Every change needs a reason. Try it as a simulation first:
openwaf-cloud ctl records add example.com type=TXT name=_cli-test content="hello" \
--reason "Try the CLI" --dry-runThe CLI prints Simulación sobre zona example.com: versión 7 → 8 ("simulation on zone … version 7 → 8") and the diff. Run it again without --dry-run: it simulates, shows the diff, asks ¿Aplicar? [s/N] ("apply?") and applies when you answer y. Then undo it:
openwaf-cloud ctl records rm example.com _cli-test/TXT --reason "Remove the CLI test"Next: Changes: simulation and confirmation and the command reference.