# Usar el CLI con IA y scripts

> Convenciones del CLI para agentes de IA, scripts y CI: JSON, paginación, errores, confirmaciones, workspaces y sesiones de solo lectura

Fuente: https://developers.plazbot.com/cli/ia/scripting/

### Usar el CLI con IA y scripts

Todos los comandos del CLI siguen las mismas reglas, pensadas para que los use un script, un pipeline de CI o un agente de IA como Claude Code. Esta página las reúne.

### Flujo recomendado para Claude Code

```bash
# 1. Sesión de solo lectura (la IA puede consultar todo pero no cambiar nada)
plazbot login --read-only

# 2. Enseñarle a Claude Code a usar el CLI
plazbot skill install

# 3. Comprobar que el token funciona
plazbot whoami --verify
```

Después puedes pedirle a Claude cosas como "¿por qué falló la campaña de ayer?" o "¿en qué paso de la automatización está el contacto +51912345678?". Para tareas que cambian datos, usa una sesión normal (`plazbot login`). Ver [`plazbot skill`](https://developers.plazbot.com/cli/ia/skill) y [`plazbot login`](https://developers.plazbot.com/cli/login).

### Salida JSON

- `--json` existe en todo comando que lista, lee o modifica datos. Con `--json`, stdout solo trae JSON; los mensajes de progreso van a stderr.
- [`plazbot api`](https://developers.plazbot.com/cli/ia/api) siempre imprime JSON, sin necesidad de `--json`.
- [`plazbot commands --json`](https://developers.plazbot.com/cli/ia/commands) describe todos los comandos y sus opciones.

### Listados y paginación

Con `--json`, todos los listados devuelven el mismo formato:

```json
{
"data": [ { "id": "con_AbcDef123" } ],
"nextCursor": "..."
}
```

`nextCursor` es `null` cuando no hay más resultados.

| Flag | Descripción |
|------|-------------|
| `--limit <n>` | Para de pedir páginas al llegar a N elementos. Las páginas de la API no se cortan, así que puede devolver algunos más |
| `--cursor <token>` | Continúa desde el `nextCursor` de una llamada anterior |
| `--all` | Trae todas las páginas, hasta 5000 elementos. Si queda más, avisa en stderr y deja `nextCursor` para seguir |

```bash
# Primera página
plazbot contacts list --limit 100 --json > pagina1.json

# Siguiente página
plazbot contacts list --limit 100 --cursor "$(jq -r '.nextCursor' pagina1.json)" --json
```

Prefiere filtros y límites pequeños: un workspace grande tiene decenas de miles de contactos y cada página consume capacidad de la base de datos.

### Errores y códigos de salida

- `0` significa éxito. `1` significa que algo falló, también en fallos parciales.
- En modo JSON el error va a stderr con este formato:

```json
{"error":{"message":"Contact con_AbcDef123 not found in workspace wok_AbcDef123.","code":"not_found","hint":"..."}}
```

| `code` | Significado |
|--------|-------------|
| `not_signed_in` | No hay sesión. Ejecuta `plazbot login` |
| `unauthorized` | Token inválido, vencido o revocado |
| `forbidden` | Sin permiso para esa acción o ese workspace |
| `read_only` | La sesión es de solo lectura |
| `not_found` | ID o recurso inexistente |
| `confirmation_required` | Falta `--yes` en un comando que cambia datos |
| `rate_limited` | Demasiados requests; espera unos segundos |
| `invalid_argument` | Flag o valor inválido |
| `api_error` | La API respondió con error (incluye `{"success": false}` con HTTP 200) |

### Confirmaciones

- Los comandos que crean, cambian, borran o envían piden confirmación.
- `-y, --yes` la omite (también funcionan `--confirm` y `-f`).
- Sin terminal interactiva (CI, pipes, agentes) o con `--json`, nunca se quedan esperando: fallan con `confirmation_required` hasta que pases `--yes`.

### Workspaces y zonas

Los comandos usan el workspace activo de la sesión. Si perteneces a varios workspaces, puedes apuntar a otro solo para un comando:

```bash
plazbot workspace list --json
plazbot contacts list -w wok_AbcDef123 -z EU --json
```

`-w, --workspace` y `-z, --zone` existen en los comandos de datos (contactos, mensajes, campañas, reportes, automatizaciones, `plazbot api`...). Para cambiar el workspace de forma permanente usa [`plazbot workspace use`](https://developers.plazbot.com/cli/workspace).

### Variables de entorno

En CI o en servidores, en lugar de `plazbot login`:

| Variable | Requerida | Descripción |
|----------|-----------|-------------|
| `PLAZBOT_API_KEY` | Sí | API key o token de la cuenta |
| `PLAZBOT_WORKSPACE_ID` | Sí | Workspace por defecto (`wok_...`) |
| `PLAZBOT_ZONE` | No | `LA` (por defecto) o `EU` |
| `PLAZBOT_USER_ID` | No | Tu ID de usuario (`usr_...`). Lo necesitan las vistas filtradas por "usuario actual" y `views list` |

Las variables tienen prioridad sobre la sesión guardada en `~/.plazbot/config.json`.

### Sesiones de solo lectura

`plazbot login --read-only` crea un token que solo puede hacer consultas: la API rechaza cualquier POST, PUT, PATCH o DELETE con ese token (error `read_only`). Es la forma recomendada de darle acceso a una IA o a un script de reportes. [`plazbot whoami`](https://developers.plazbot.com/cli/whoami) muestra si la sesión activa es de solo lectura.

Ten en cuenta que algunos comandos de lectura usan POST en la API (por ejemplo `agent message`), así que con una sesión de solo lectura tampoco funcionan.