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

# Workflows y pruebas

> Crea y valida workflows, pruébalos localmente con trazas y un dashboard, depura conversaciones de producción con jelou logs y reinicia el estado de un usuario.

Estos comandos cubren el ciclo de construir, probar y depurar los workflows de
un proyecto: autoría y validación (`jelou workflow`), pruebas locales con trazas
(`jelou test`), triaje de producción (`jelou logs`) y reinicio de estado de
usuario (`jelou users`).

<Note>
  La sincronización de workflows a archivos locales (`jelou link`, `pull`,
  `status`, `push`, `incoming`) se documenta en
  [Proyectos y canales](/guides/cli/project).
</Note>

## `jelou workflow`

| Subcomando                              | Descripción                                                                                                                                               |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list [--project-id <id>]`              | Lista proyectos; con `--project-id`, lista los skills/canales del proyecto                                                                                |
| `create --project-id <id> --name "<n>"` | Crea un workflow nuevo en un proyecto                                                                                                                     |
| `node-spec [<tipo>] [--list]`           | Imprime el schema de un tipo de nodo (con `--list` lista todos los tipos, o pásale un nombre de tipo para su JSON completo) sin cargar el catálogo entero |
| `validate [<archivo>]`                  | Valida los `workflows/*.json` contra el validador canónico                                                                                                |

<Note>
  `jelou workflow` tiene 16 subcomandos en total (además de los de arriba:
  `update`, `set-default`, `delete`/`rm`, `hide`, `unhide`, `allow-user`,
  `allow-country`, `evaluate`, `skill`, `build`, `branches`,
  `canonicalize-branch`, `inject-ecommerce`, `adopt`, `authoring`). Explóralos
  con `jelou workflow --describe`.
</Note>

```bash theme={null}
jelou workflow list
jelou workflow list --project-id 01kf13bcth4ytadcx9h8pq8w9h --agent
jelou workflow create --project-id 01kf13bcth4ytadcx9h8pq8w9h --name "Generación de Orden V3"
jelou workflow node-spec --list
jelou workflow node-spec AI_TASK
jelou workflow validate
jelou workflow validate workflows/saludo.whatsapp.json
jelou workflow validate --allow-warnings
jelou workflow validate --fix workflows/borrador.json
jelou workflow validate --partial workflows/borrador.json
```

`validate` corre una tubería canónica de varias fases (schema → autofix →
normalize → ids → config → quality → whatsapp → edges → lint → finalize) y
reporta `{ status, errorCount, warnCount }` por fase. Con errores sale con
código distinto de 0; `--allow-warnings` sale 0 si solo quedan advertencias.

Flags adicionales: `--fix` (alias `--write`) canoniza el archivo en el mismo
lugar (acuña ids, normaliza tokens de branch, repara handles de edges);
`--quiet` solo imprime los archivos con errores o advertencias; `--out <path>` guarda el mismo payload JSON en disco además de en stdout.

Con `--partial <archivo>` corres el validador completo sobre un borrador en
progreso en modo *preview*: devuelve diagnósticos completos pero nunca
bloquea — siempre sale con código 0 sin importar los errores. Desde la v1.88,
un hook de "validar al escribir" corre este mismo preview automáticamente en
el instante en que un agente de IA escribe el JSON de un workflow, así que
los diagnósticos llegan de inmediato (son solo informativos: nunca bloquean
la escritura).

También desde la v1.88, `validate` valida además los `tools/*.json` (no solo
`workflows/*.json`) con las reglas reales de push de tools, y ya no marca por
error `$output.set()` dentro de un nodo CODE de una tool — esa es la forma
correcta en que una tool devuelve un valor.

## `jelou test`

Prueba workflows localmente: envía mensajes, persiste trazas y chats, e
inspecciónalos.

| Subcomando                                    | Descripción                                                                                                                                   |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `tool <slug> --input k=v`                     | Ejecuta una tool en el servidor y reporta qué output disparó (en el propio `--help` del CLI, `tool` ahora encabeza la lista, antes de `send`) |
| `send text --target <slug> --message "<txt>"` | Envía un mensaje a un workflow y persiste la traza                                                                                            |
| `turn status <execution-id> --target <slug>`  | Sigue un turno en curso con long-poll hasta que cierra                                                                                        |
| `chats list --target <slug>`                  | Lista los chats (ejecuciones) registrados                                                                                                     |
| `chats show <id> --target <slug>`             | Detalle de un chat (turnos + salida renderizada)                                                                                              |
| `trace <execution-id> --target <slug>`        | Inspecciona la traza de una ejecución                                                                                                         |
| `grep <consulta> --target <slug>`             | Búsqueda de texto completo en los mensajes de usuario/asistente registrados                                                                   |
| `stats --target <slug>`                       | Conteos agregados, desglose por estado terminal y tamaño de la `qa.db`                                                                        |
| `reset <execution-id> --target <slug>`        | Limpia la caché del gateway de una ejecución para volver a correrla desde el inicio                                                           |
| `cleanup --target <slug>`                     | Elimina corridas antiguas de `qa.db` según la política de retención                                                                           |
| `dashboard`                                   | Inicia el dashboard local de pruebas                                                                                                          |
| `finish <execution-id> --target <slug>`       | Marca una corrida registrada con veredicto PASS/FAIL/INCONCLUSIVE                                                                             |
| `whatsapp <verbo>`                            | Pruebas con una cuenta real de WhatsApp (experimental)                                                                                        |

```bash theme={null}
jelou test tool generar-otp --input identificacion=0912345678
jelou test send text --target saludo-web --message "hola"
jelou test send text --target saludo-web --execution <id> --message "siguiente"
jelou test chats list --target saludo-web --terminal TIMEOUT --since 7d --json
jelou test trace sKI7morplA4LKUAX51Mqx --target saludo-web
```

### Dashboard local de pruebas

```bash theme={null}
jelou test dashboard            # abre el navegador en http://127.0.0.1:8766
jelou test dashboard --port 9090
jelou test dashboard --repo otro-repo--abc123   # lee la qa.db de otro repo
jelou test dashboard --no-open
```

Levanta una **interfaz web local de una sola URL** (servidor Hono + UI React)
para inspeccionar visualmente tus pruebas de workflows — es la versión gráfica
de lo que producen `jelou test send text`, `jelou test chats list` y
`jelou test trace`.

**Qué muestra:**

* **Targets / workflows** — los workflows que puedes probar (los que tienen
  corridas registradas, más los del lockfile aunque aún no tengan ninguna).
* **Runs (chats de prueba)** — cada conversación de prueba registrada, con sus
  turnos, el mensaje renderizado y su estado terminal (`STABLE`, `TIMEOUT`,
  `HARNESS_STALL`, `HARNESS_ERROR`).
* **Traza por nodo** — para cada run, la ejecución paso a paso del workflow:
  cada nodo con su estado inicial y final.

Internamente sirve estos endpoints de solo lectura
(`/api/targets`, `/api/workflows`, `/api/runs`, `/api/runs/:id`,
`/api/runs/:id/trace`) y, si hay un perfil que pueda enviar mensajes, permite
**iniciar chats nuevos** desde la UI (`POST /api/chats`,
`/api/runs/:id/messages`).

**Con qué datos trabaja:**

* Lee los archivos **`qa.db`** (SQLite) por target — los **mismos** que crean y
  consultan los demás comandos `jelou test`. No hay una base aparte: el
  dashboard solo los visualiza.
* Los datos se aíslan por **repo** (segmento `repo-id` = nombre del directorio
  raíz de git + un hash corto) y por **perfil**. Por eso debes ejecutarlo dentro
  del repo con tus corridas, o apuntar a otro con `--repo <segmento>`.

| Flag                   | Descripción                                                          |
| ---------------------- | -------------------------------------------------------------------- |
| `--port <n>`           | Puerto TCP (default 8766; si está ocupado, usa uno libre)            |
| `--host <host>`        | Host a bindear (debe ser loopback: `127.0.0.1`, `::1` o `localhost`) |
| `--repo <segmento>`    | Lee la `qa.db` de otro repo en vez del actual                        |
| `--open` / `--no-open` | Abrir (o no) el navegador automáticamente                            |

Es **solo local** (escucha en loopback); para acceso remoto usa reenvío de
puertos por SSH: `ssh -L 8766:localhost:8766 <host>`.

<Note>
  Los bundles BrainOps `jelou-build-workflow` y `jelou-test-workflow`
  ([skills](/guides/cli/skills)) orquestan este ciclo de construir y probar
  workflows desde un agente de IA.
</Note>

## `jelou logs` — triaje de conversaciones de producción

Acceso **solo lectura** al historial de conversaciones de un bot. Permite bajar
de conversación → línea de tiempo del chat → nodo que falló.

| Subcomando                                | Descripción                                            |
| ----------------------------------------- | ------------------------------------------------------ |
| `conversations list --bot-id <id>`        | Lista conversaciones (una fila por usuario × día)      |
| `chat --bot-id <id> --user-id <tel>`      | Línea de tiempo de un usuario (mensajes + ejecuciones) |
| `node --execution-id <id> --node-id <id>` | Depura una sola ejecución de nodo                      |

```bash theme={null}
jelou logs conversations list --bot-id d42d688c-1c3f-4b99-9f32-70e14a10b365
jelou logs conversations list --bot-id d42d688c-… --message "devolución"
jelou logs chat --bot-id d42d688c-… --user-id 593959216623 --failed-only
jelou logs node --execution-id sKI7morplA4LKUAX51Mqx --node-id 69eb6c946b3d065a3bc6cc44
```

Todos aceptan `--from`/`--to` (ISO-8601), `--cursor` para paginar y `--out <path>` para guardar el envelope JSON. El `--bot-id` es el bot conectado al
canal — descúbrelo con `jelou channels list`. El flujo de drill-down imprime el
siguiente comando bajo cada ejecución FAILED.

## `jelou users reset`

Reinicia en duro el estado cacheado de un usuario con un bot (borra las claves
`state`, `skill` y `state_manual`). Útil antes de re-probar desde cero o para
desbloquear a un usuario atascado en un bucle.

```bash theme={null}
jelou users reset --bot-id d42d688c-… --user-id 593959216623 --yes
jelou users reset --channel-id 01KR… --user-id 593959216623 --yes
```

<Warning>
  Es destructivo: las conversaciones en curso pierden su contexto. `--bot-id` y
  `--channel-id` son mutuamente excluyentes; bajo `--agent`/`--no-input` se
  requiere `--yes`.
</Warning>