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

01# 1. Sesión de solo lectura (la IA puede consultar todo pero no cambiar nada)
02plazbot login --read-only
03 
04# 2. Enseñarle a Claude Code a usar el CLI
05plazbot skill install
06 
07# 3. Comprobar que el token funciona
08plazbot 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 y plazbot 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 siempre imprime JSON, sin necesidad de --json.
plazbot commands --json describe todos los comandos y sus opciones.

Listados y paginación

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

json

01{
02  "data": [ { "id": "con_AbcDef123" } ],
03  "nextCursor": "..."
04}

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

01# Primera página
02plazbot contacts list --limit 100 --json > pagina1.json
03 
04# Siguiente página
05plazbot 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

01{"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

01plazbot workspace list --json
02plazbot 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.

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