# Bienvenidos al CLI

> Gestiona tus agentes de IA, WhatsApp, workers y portales desde la terminal

Fuente: https://developers.plazbot.com/cli/introduccion/

## Alcance del CLI

**Plazbot CLI** es la herramienta oficial de línea de comandos para trabajar con la plataforma Plazbot. Permite gestionar todo tu ecosistema de IA sin salir de la terminal.

### Qué puedes hacer

- **Agentes de IA**: crear agentes con un asistente interactivo, plantillas o archivos JSON; chatear con ellos, gestionar su base de conocimiento y configurar Tool Calling.
- **Portal**: crear el portal web del workspace, asociarle agentes y gestionar sus enlaces.
- **WhatsApp**: conectar números, enviar mensajes y plantillas, envíos masivos y webhooks.
- **Workers**: desplegar código propio (tools, syncs, tareas programadas, webhooks) y gestionar sus secretos.
- **Studio**: crear y diagnosticar agentes conversando en la terminal.
- **Sesión**: iniciar sesión desde el navegador una vez y cambiar entre tus workspaces. Con `--read-only` el token solo puede consultar.
- **Datos del workspace**: contactos, mensajes, etiquetas, oportunidades, tareas, llamadas, plantillas, campañas, automatizaciones, secuencias, reportes, equipo, vistas y webhooks.
- **IA y scripting**: `--json` en todos los comandos, `plazbot api` para llamar a cualquier endpoint de la API, `plazbot commands --json` y una skill para que Claude Code use el CLI.

### Instalación

```bash
npm install -g plazbot-cli
```

Requiere Node.js 18.17 o superior. Detalle en [Instalación](https://developers.plazbot.com/cli/instalacion).

### Inicio rápido

```bash
# 1. Iniciar sesión desde el navegador (sin copiar API key)
plazbot login

# 2. Crear un agente con el asistente interactivo
plazbot agent create

# 3. Chatear con tu agente
plazbot agent chat age_AbcDef123

# 4. Ver todos tus agentes
plazbot agent list
```

Para WhatsApp (conectar tu número y enviar tu primer mensaje) ve a la pestaña [WhatsApp](https://developers.plazbot.com/whatsapp/quickstart).

> **Tip:** Todos los comandos tienen ayuda con ejemplos: `plazbot <comando> --help`, por ejemplo `plazbot portal create --help`.

---

### Uso en scripts y CI

El CLI está pensado para usarse también desde scripts, pipelines y otros agentes:

- **`--json`**: los comandos que leen, listan o cambian datos aceptan `--json`. La salida estándar contiene solo JSON (los mensajes y spinners van a stderr), y los errores se escriben en stderr como `{"error":{"message","code","hint"}}`.
- **`-y, --yes`**: omite las confirmaciones de los comandos destructivos (eliminar, desvincular, envíos masivos). Sin terminal interactiva y sin `--yes`, esos comandos fallan con `This action needs confirmation and there is no interactive terminal.` en lugar de quedarse esperando. Si respondes que no a una confirmación, el comando imprime `Aborted.` y termina con código `1`.
- **Códigos de salida**: `0` si todo salió bien y `1` ante cualquier fallo, incluidos los fallos parciales (por ejemplo, un envío masivo con algún número inválido).
- **Números de teléfono**: siempre con `-p, --phone <number>`, en cualquier formato internacional (`+51912345678`, `"+51 912 345 678"`, `0051...`).
- **Sesión sin navegador**: en CI usa las variables `PLAZBOT_API_KEY`, `PLAZBOT_WORKSPACE_ID` y `PLAZBOT_ZONE`, o [`plazbot init`](https://developers.plazbot.com/cli/init).

```bash
# Crear un agente desde un archivo y capturar su ID
AGENT_ID=$(plazbot agent create ./agent.json --json | jq -r '.id')

# Eliminar sin confirmación
plazbot agent delete "$AGENT_ID" --yes

# Comprobar la sesión antes de continuar
plazbot whoami > /dev/null 2>&1 || exit 1
```

---

### Comandos disponibles

  <Card
    title="Sesión"
    icon="lock-open"
    href="/cli/login"
  >
    Inicia sesión desde el navegador, revisa la sesión activa y cambia de workspace.
  </Card>
  <Card
    title="IA y scripting"
    icon="robot"
    href="/cli/ia/scripting"
  >
    Usa el CLI desde Claude Code u otros agentes: JSON, paginación, `plazbot api` y la skill.
  </Card>
  <Card
    title="Contactos y conversaciones"
    icon="address-book"
    href="/cli/contacts/list"
  >
    Busca contactos, lee sus mensajes, etiquétalos y muévelos de fase.
  </Card>
  <Card
    title="Automatizaciones y campañas"
    icon="diagram-project"
    href="/cli/automations/list"
  >
    Revisa flujos, dónde está cada contacto, campañas, plantillas, secuencias y reportes.
  </Card>
  <Card
    title="Agentes de IA"
    icon="message-bot"
    href="/cli/agent/create"
  >
    Crear agentes con asistente, plantillas o JSON; actualizar, listar, chatear y gestionar widgets.
  </Card>
  <Card
    title="Portal de IA"
    icon="window-flip"
    href="/cli/portal/create"
  >
    Crear el portal del workspace y gestionar sus agentes y enlaces.
  </Card>
  <Card
    title="WhatsApp for Developers"
    icon="whatsapp"
    href="/whatsapp/quickstart"
  >
    Conecta tu número y envía tu primer mensaje con plazbot login y plazbot whatsapp setup.
  </Card>

---

### Referencia rápida

| Comando | Descripción |
|---------|-------------|
| `plazbot login` | Iniciar sesión desde el navegador |
| `plazbot whoami` | Ver cuenta, workspace y zona activos |
| `plazbot workspace list` | Listar tus workspaces |
| `plazbot workspace use <workspaceId>` | Cambiar el workspace activo |
| `plazbot init -k <apiKey> -w <workspaceId> -z LA` | Guardar una API key manualmente (CI) |
| `plazbot logout` | Cerrar la sesión en este equipo |
| `plazbot agent create` | Crear un agente (asistente interactivo) |
| `plazbot agent create ./agent.json` | Crear un agente desde un archivo JSON |
| `plazbot agent list` | Listar los agentes |
| `plazbot agent get <agentId>` | Ver el detalle de un agente |
| `plazbot agent chat <agentId>` | Chat interactivo con un agente |
| `plazbot agent message <agentId> -q "pregunta"` | Enviar un mensaje puntual |
| `plazbot agent update <agentId> ./changes.json` | Actualizar un agente (solo los campos del archivo) |
| `plazbot agent enable-widget <agentId>` | Activar el widget web |
| `plazbot agent delete <agentId>` | Eliminar un agente |
| `plazbot agent export <agentId> -o agent.json` | Exportar la configuración de un agente |
| `plazbot agent monitor <agentId>` | Ver la actividad del agente en tiempo real |
| `plazbot portal list` | Ver el portal del workspace |
| `plazbot portal get <portalId>` | Ver el detalle de un portal |
| `plazbot portal create -n "Help Center" -t "Bienvenido"` | Crear el portal |
| `plazbot portal add-agent <portalId> -a <agentId>` | Asociar un agente al portal |
| `plazbot portal remove-agent <portalId> -a <agentId>` | Quitar un agente del portal |
| `plazbot whatsapp setup` | Asistente: conectar WhatsApp y enviar tu primer mensaje |
| `plazbot whatsapp connect` | Conectar un número de WhatsApp |
| `plazbot whatsapp send-message -p <número> -m "mensaje"` | Enviar un mensaje de texto |
| `plazbot whatsapp send-template -p <número> -t <plantilla>` | Enviar una plantilla |
| `plazbot whatsapp broadcast -t <plantilla> --phones numeros.txt` | Envío masivo de una plantilla |
| `plazbot whatsapp assign -p <número> -a <agentId>` | Asignar un agente a un número |
| `plazbot workers deploy` | Desplegar los workers de `./workers` |
| `plazbot workers list` | Listar los workers |
| `plazbot workers secret set <KEY>` | Guardar un secreto para los workers (pide el valor) |
| `plazbot studio` | Abrir Studio (chat para crear y diagnosticar agentes) |
| `plazbot studio ask "pregunta"` | Consulta puntual a Studio, sin abrir el chat |
| `plazbot login --read-only` | Sesión que solo puede consultar (para agentes de IA) |
| `plazbot whoami --verify` | Comprobar que el token sigue funcionando |
| `plazbot skill install` | Enseñarle a Claude Code a usar el CLI |
| `plazbot commands --json` | Todos los comandos, argumentos y opciones en JSON |
| `plazbot api get /api/workspace/{ws}` | Llamar a cualquier endpoint de la API |
| `plazbot workspace show tags` | Ver la configuración del workspace (etiquetas, fases, canales…) |
| `plazbot contacts search -p <número>` | Buscar un contacto |
| `plazbot contacts update <contactId> --add-tag <tagId>` | Etiquetar un contacto o cambiarle la fase |
| `plazbot messages list <contactId>` | Ver la conversación de un contacto |
| `plazbot campaigns records <campaignId> --failed` | Ver los envíos fallidos de una campaña |
| `plazbot automations state <contactId>` | Ver en qué flujo y nodo está un contacto |
| `plazbot reports messages --from 2026-10-01 --to 2026-10-07` | Reporte de mensajes |
| `plazbot team list` | Miembros del workspace |