> ## 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 e testes

> Crie e valide workflows, teste-os localmente com traces e um dashboard, depure conversas de produção com jelou logs e reinicie o estado de um usuário.

Estes comandos cobrem o ciclo de construir, testar e depurar os workflows de
um projeto: autoria e validação (`jelou workflow`), testes locais com traces
(`jelou test`), triagem de produção (`jelou logs`) e reinício de estado de
usuário (`jelou users`).

<Note>
  A sincronização de workflows para arquivos locais (`jelou link`, `pull`,
  `status`, `push`, `incoming`) está documentada em
  [Projetos e canais](/pt/guias/cli/project).
</Note>

## `jelou workflow`

| Subcomando                              | Descrição                                                                                                                                                 |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list [--project-id <id>]`              | Lista projetos; com `--project-id`, lista as skills/canais do projeto                                                                                     |
| `create --project-id <id> --name "<n>"` | Cria um workflow novo em um projeto                                                                                                                       |
| `node-spec [<tipo>] [--list]`           | Imprime o schema de um tipo de nó (com `--list` lista todos os tipos, ou passe um nome de tipo para o JSON completo dele) sem carregar o catálogo inteiro |
| `validate [<arquivo>]`                  | Valida os `workflows/*.json` contra o validador canônico                                                                                                  |

<Note>
  `jelou workflow` tem 16 subcomandos no total (além dos de cima: `update`,
  `set-default`, `delete`/`rm`, `hide`, `unhide`, `allow-user`,
  `allow-country`, `evaluate`, `skill`, `build`, `branches`,
  `canonicalize-branch`, `inject-ecommerce`, `adopt`, `authoring`). Explore-os
  com `jelou workflow --describe`.
</Note>

```bash theme={null}
jelou workflow list
jelou workflow list --project-id 01kf13bcth4ytadcx9h8pq8w9h --agent
jelou workflow create --project-id 01kf13bcth4ytadcx9h8pq8w9h --name "Geração de Ordem 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/rascunho.json
jelou workflow validate --partial workflows/rascunho.json
```

`validate` roda um pipeline canônico de várias fases (schema → autofix →
normalize → ids → config → quality → whatsapp → edges → lint → finalize) e
reporta `{ status, errorCount, warnCount }` por fase. Com erros sai com
código diferente de 0; `--allow-warnings` sai 0 se restarem apenas avisos.

Flags adicionais: `--fix` (alias `--write`) canoniza o arquivo no mesmo
lugar (cunha ids, normaliza tokens de branch, repara handles de edges);
`--quiet` só imprime os arquivos com erros ou avisos; `--out <path>` salva o
mesmo payload JSON em disco além da stdout.

Com `--partial <arquivo>` você roda o validador completo sobre um rascunho
em andamento em modo *preview*: devolve diagnósticos completos, mas nunca
bloqueia — sempre sai com código 0, independente dos erros. Desde a v1.88,
um hook de "validar ao escrever" roda esse mesmo preview automaticamente no
instante em que um agente de IA escreve o JSON de um workflow, então os
diagnósticos chegam imediatamente (são apenas informativos: nunca bloqueiam
a escrita).

Também desde a v1.88, `validate` passou a validar os `tools/*.json` também
(não só os `workflows/*.json`) com as regras reais de push de tools, e não
marca mais por erro o `$output.set()` dentro de um nó CODE de uma tool —
essa é a forma correta de uma tool devolver um valor.

## `jelou test`

Testa workflows localmente: envia mensagens, persiste traces e chats, e
inspeciona-os.

| Subcomando                                    | Descrição                                                                                                                                |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `tool <slug> --input k=v`                     | Executa uma tool no servidor e reporta qual output disparou (no próprio `--help` do CLI, `tool` agora encabeça a lista, antes de `send`) |
| `send text --target <slug> --message "<txt>"` | Envia uma mensagem a um workflow e persiste o trace                                                                                      |
| `turn status <execution-id> --target <slug>`  | Acompanha um turno em andamento com long-poll até fechar                                                                                 |
| `chats list --target <slug>`                  | Lista os chats (execuções) registrados                                                                                                   |
| `chats show <id> --target <slug>`             | Detalhe de um chat (turnos + saída renderizada)                                                                                          |
| `trace <execution-id> --target <slug>`        | Inspeciona o trace de uma execução                                                                                                       |
| `grep <consulta> --target <slug>`             | Busca de texto completo nas mensagens de usuário/assistente registradas                                                                  |
| `stats --target <slug>`                       | Contagens agregadas, detalhamento por estado terminal e tamanho da `qa.db`                                                               |
| `reset <execution-id> --target <slug>`        | Limpa o cache do gateway de uma execução para rodá-la de novo desde o início                                                             |
| `cleanup --target <slug>`                     | Remove execuções antigas da `qa.db` conforme a política de retenção                                                                      |
| `dashboard`                                   | Inicia o dashboard local de testes                                                                                                       |
| `finish <execution-id> --target <slug>`       | Marca uma execução registrada com veredito PASS/FAIL/INCONCLUSIVE                                                                        |
| `whatsapp <verbo>`                            | Testes com uma conta 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 testes

```bash theme={null}
jelou test dashboard            # abre o navegador em http://127.0.0.1:8766
jelou test dashboard --port 9090
jelou test dashboard --repo outro-repo--abc123   # lê a qa.db de outro repo
jelou test dashboard --no-open
```

Sobe uma **interface web local de uma única URL** (servidor Hono + UI React)
para inspecionar visualmente seus testes de workflows — é a versão gráfica
do que produzem `jelou test send text`, `jelou test chats list` e
`jelou test trace`.

**O que mostra:**

* **Targets / workflows** — os workflows que você pode testar (os que têm
  execuções registradas, mais os do lockfile mesmo que ainda não tenham
  nenhuma).
* **Runs (chats de teste)** — cada conversa de teste registrada, com seus
  turnos, a mensagem renderizada e seu estado terminal (`STABLE`, `TIMEOUT`,
  `HARNESS_STALL`, `HARNESS_ERROR`).
* **Trace por nó** — para cada run, a execução passo a passo do workflow:
  cada nó com seu estado inicial e final.

Internamente serve estes endpoints somente leitura
(`/api/targets`, `/api/workflows`, `/api/runs`, `/api/runs/:id`,
`/api/runs/:id/trace`) e, se houver um perfil que possa enviar mensagens, permite
**iniciar chats novos** a partir da UI (`POST /api/chats`,
`/api/runs/:id/messages`).

**Com quais dados trabalha:**

* Lê os arquivos **`qa.db`** (SQLite) por target — os **mesmos** que criam e
  consultam os demais comandos `jelou test`. Não há um banco separado: o
  dashboard apenas os visualiza.
* Os dados são isolados por **repo** (segmento `repo-id` = nome do diretório
  raiz do git + um hash curto) e por **perfil**. Por isso você deve executá-lo
  dentro do repo com suas execuções, ou apontar para outro com `--repo <segmento>`.

| Flag                   | Descrição                                                                   |
| ---------------------- | --------------------------------------------------------------------------- |
| `--port <n>`           | Porta TCP (default 8766; se estiver ocupada, usa uma livre)                 |
| `--host <host>`        | Host para fazer bind (deve ser loopback: `127.0.0.1`, `::1` ou `localhost`) |
| `--repo <segmento>`    | Lê a `qa.db` de outro repo em vez do atual                                  |
| `--open` / `--no-open` | Abrir (ou não) o navegador automaticamente                                  |

É **apenas local** (escuta no loopback); para acesso remoto use encaminhamento
de portas por SSH: `ssh -L 8766:localhost:8766 <host>`.

<Note>
  Os bundles BrainOps `jelou-build-workflow` e `jelou-test-workflow`
  ([skills](/pt/guias/cli/skills)) orquestram este ciclo de construir e testar
  workflows a partir de um agente de IA.
</Note>

## `jelou logs` — triagem de conversas de produção

Acesso **somente leitura** ao histórico de conversas de um bot. Permite descer
de conversa → linha do tempo do chat → nó que falhou.

| Subcomando                                | Descrição                                            |
| ----------------------------------------- | ---------------------------------------------------- |
| `conversations list --bot-id <id>`        | Lista conversas (uma linha por usuário × dia)        |
| `chat --bot-id <id> --user-id <tel>`      | Linha do tempo de um usuário (mensagens + execuções) |
| `node --execution-id <id> --node-id <id>` | Depura uma única execução de nó                      |

```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 aceitam `--from`/`--to` (ISO-8601), `--cursor` para paginar e `--out <path>` para salvar o envelope JSON. O `--bot-id` é o bot conectado ao
canal — descubra-o com `jelou channels list`. O fluxo de drill-down imprime o
próximo comando abaixo de cada execução FAILED.

## `jelou users reset`

Reinicia em modo duro o estado em cache de um usuário com um bot (apaga as chaves
`state`, `skill` e `state_manual`). Útil antes de retestar do zero ou para
desbloquear um usuário preso em um loop.

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

<Warning>
  É destrutivo: as conversas em andamento perdem seu contexto. `--bot-id` e
  `--channel-id` são mutuamente exclusivos; sob `--agent`/`--no-input` é
  necessário `--yes`.
</Warning>