# Primeros pasos con la CLI

> Consigue openwaf-cloud, apúntala a la API de OpenWAF, dale un token de API de forma segura y ejecuta tu primera consulta y tu primer cambio.

## Conseguir la CLI

`openwaf-cloud` es un único binario. OpenWAF todavía no publica versiones descargables; si quieres usarla, pídela en support@openwaf.dev. Todo lo que hace está también disponible desde el panel, la [API](https://developers.openwaf.dev/es/api/), los [SDK](https://developers.openwaf.dev/es/sdk/) y el [servidor MCP](https://developers.openwaf.dev/es/mcp/).

Comprueba que funciona:

```sh
openwaf-cloud ctl help
```

## Apuntarla a la API

Define la dirección de la API una vez en el perfil de tu shell. La CLI añade ella misma las rutas `/v1/…`, así que basta con el host:

```sh
export OPENWAF_API_URL=https://dash.openwaf.dev
```

> **Atención**
>
> Define siempre `OPENWAF_API_URL` (o pasa `--api https://dash.openwaf.dev`). Sin ella, la CLI intenta una dirección local y falla con `no se puede hablar con la API`.


## Darle un token

Crea un token de API en el panel, en **Tokens de API**, con el rol y el alcance que necesites: **Solo lectura** basta para consultar y **Técnico** permite hacer cambios. Los tokens empiezan por `owf_`.

La CLI nunca acepta el token como argumento, para que no acabe en el historial de la shell ni en la lista de procesos. Usa una de estas dos vías:

**Fichero del token**

Guarda el token en un fichero que solo puedas leer tú. Puede contener solo el token o una única línea `NOMBRE_TOKEN=valor`, así que también sirve un fichero al estilo `.env`.

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

La CLI rechaza un fichero que no sea tuyo o que puedan leer el grupo u otros usuarios.
**Variable de entorno**

```sh
read -rs OPENWAF_TOKEN && export OPENWAF_TOKEN
```

Útil en CI, donde el token sale del almacén de secretos del pipeline.


Define solo una de `OPENWAF_TOKEN` y `OPENWAF_TOKEN_FILE`; con las dos, la CLI se detiene.

## Elegir la organización

Un token pertenece a una organización y la CLI usa esa por defecto. Para indicarla explícitamente, define `OPENWAF_ORG` (o `--org`) con su nombre o su id:

```sh
export OPENWAF_ORG=acme
```

## Primera consulta

```sh
openwaf-cloud ctl zones list
openwaf-cloud ctl zones show example.com
openwaf-cloud ctl records list example.com
```

Las zonas se nombran por su dominio o por su id. Añade `--json` a cualquier consulta para obtener la respuesta de la API tal cual.

## Primer cambio

Todo cambio necesita un motivo. Pruébalo primero como simulación:

```sh
openwaf-cloud ctl records add example.com type=TXT name=_cli-test content="hola" \
  --reason "Probar la CLI" --dry-run
```

La CLI imprime `Simulación sobre zona example.com: versión 7 → 8` y las diferencias. Repite la orden sin `--dry-run`: simula, enseña las diferencias, pregunta `¿Aplicar? [s/N]` y aplica cuando respondes `s`. Después deshazlo:

```sh
openwaf-cloud ctl records rm example.com _cli-test/TXT --reason "Quitar la prueba de la CLI"
```

Sigue con [Cambios: simulación y confirmación](https://developers.openwaf.dev/es/cli/changes/) y la [referencia de órdenes](https://developers.openwaf.dev/es/cli/reference/zones/).