> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plazbot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Modo One-shot

> Ejecuta una sola consulta de Studio sin entrar al REPL — ideal para scripts y CI

## Para que sirve

El subcomando `plazbot studio ask` envia un solo mensaje a Studio, imprime la respuesta a `stdout` y sale con codigo `0`. No abre el TUI, no consume teclas, no requiere terminal interactivo.

Ideal para:

* **Scripts de bash** que automatizan tareas con IA
* **CI/CD pipelines** que validan configuraciones de agentes
* **Cron jobs** que generan reportes (`/diagnose` programado)
* **Integraciones** con otras herramientas via stdout/stderr

```bash theme={null}
plazbot studio ask "<mensaje>"
```

### Flags

| Flag                      | Tipo   | Descripcion                                                          |
| ------------------------- | ------ | -------------------------------------------------------------------- |
| `<message>`               | string | Mensaje positional requerido                                         |
| `--dev`                   | bool   | Apunta al backend local `localhost:5090`                             |
| `-a, --agent-id <id>`     | string | Pre-carga un agente antes de ejecutar                                |
| `-w, --workspace-id <id>` | string | Sobrescribe el workspace del config (modo soporte / white-label)     |
| `--json`                  | bool   | Imprime NDJSON crudo (un chunk por linea) en vez de texto formateado |

***

## Ejemplos

### Pregunta simple

```bash theme={null}
plazbot studio ask "cuantos agentes tengo activos en este workspace"
```

Salida:

```text theme={null}
Tienes 4 agentes activos:

- Catalogo WA (WhatsApp) — actualizado hace 2 dias
- Soporte L1 (Webchat) — actualizado hace 5 horas
- Reservas (WhatsApp + Telegram)
- Demo Bot (Webchat)
```

### Diagnosticar un agente desde un script

```bash theme={null}
plazbot studio ask "diagnostica este agente" -a age_TZiOY...
```

### Soporte same-region

```bash theme={null}
# Atiende un workspace cliente dentro de tu misma zona, con tu propio usuario
plazbot studio ask "diagnostica este agente" -w wok_CLIENTE -a age_xxx
```

<Warning>
  Para atender clientes de **otra region**, primero haz `plazbot init` con una cuenta de esa zona. El JWT esta firmado por la region que lo emite.
</Warning>

### Modo NDJSON para parseo

```bash theme={null}
plazbot studio ask "lista mis agentes" --json > out.ndjson
```

Cada linea de `out.ndjson` es un chunk crudo del SSE:

```json theme={null}
{"type":"tool_call","tool_name":"list_agents","tool_id":"call_01"}
{"type":"tool_result","tool_name":"list_agents","success":true,"data":{"agents":[...]}}
{"type":"text","content":"Tienes "}
{"type":"text","content":"4 agentes activos."}
{"type":"usage","input_tokens":1247,"output_tokens":89}
{"type":"done"}
```

Util para integrar con `jq`, parsers custom o pipelines.

### Combinar con jq

```bash theme={null}
plazbot studio ask "lista mis agentes" --json \
  | jq -r 'select(.type=="tool_result" and .tool_name=="list_agents") | .data.agents[].name'
```

Imprime solo los nombres de agentes:

```text theme={null}
Catalogo WA
Soporte L1
Reservas
Demo Bot
```

***

## Codigos de salida

| Codigo | Caso                                                |
| ------ | --------------------------------------------------- |
| `0`    | Exito, respuesta completa recibida                  |
| `1`    | Error de credenciales o argumentos invalidos        |
| `2`    | Error HTTP (401, 403, 429, 5xx) — detalle en stderr |
| `3`    | Error de red o timeout                              |

```bash theme={null}
plazbot studio ask "..." || echo "fallo con codigo $?"
```

***

## Uso en CI/CD

### GitHub Actions

```yaml theme={null}
- name: Diagnose production agent
  env:
    PLAZBOT_API_KEY: ${{ secrets.PLAZBOT_API_KEY }}
    PLAZBOT_WORKSPACE: ${{ secrets.PLAZBOT_WORKSPACE }}
  run: |
    npm install -g plazbot-cli
    plazbot init -e ci@plazbot.com -k $PLAZBOT_API_KEY -w $PLAZBOT_WORKSPACE -z LA
    plazbot studio ask "diagnostica el agente prod" -a age_PROD123 --json > diagnose.ndjson
    cat diagnose.ndjson | jq 'select(.type=="tool_result") | .data.issues'
```

<Tip>
  En CI usa siempre `--json` para parsear de forma estable. El formato texto puede cambiar entre versiones, el formato NDJSON es estable.
</Tip>

<Warning>
  `ask` **no mantiene historial entre llamadas**. Cada invocacion es independiente. Si necesitas contexto persistente, usa el [modo REPL](/cli/studio/repl) o pasa todo el contexto necesario en el mensaje.
</Warning>