Workflows and testing

These commands cover the cycle of building, testing, and debugging a project’s workflows: authoring and validation (jelou workflow), local testing with traces (jelou test), production triage (jelou logs), and user state reset (jelou users).

Syncing workflows to local files (jelou link, pull, status, push, incoming) is documented in Projects and channels.

`jelou workflow`

Subcommand	Description
`list [--project-id <id>]`	Lists projects; with `--project-id`, lists the project’s skills/channels
`create --project-id <id> --name "<n>"`	Creates a new workflow in a project
`node-spec [<type>] [--list]`	Prints one node type’s schema (`--list` lists all types, or pass a type name for its full JSON) without loading the whole catalog
`validate [<file>]`	Validates the `workflows/*.json` against the canonical validator

jelou workflow has 16 subcommands in total (besides the ones above: update, set-default, delete/rm, hide, unhide, allow-user, allow-country, evaluate, skill, build, branches, canonicalize-branch, inject-ecommerce, adopt, authoring). Explore them with jelou workflow --describe.

jelou workflow list
jelou workflow list --project-id 01kf13bcth4ytadcx9h8pq8w9h --agent
jelou workflow create --project-id 01kf13bcth4ytadcx9h8pq8w9h --name "Order Generation 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/draft.json
jelou workflow validate --partial workflows/draft.json

validate runs a canonical multi-phase pipeline (schema → autofix → normalize → ids → config → quality → whatsapp → edges → lint → finalize) and reports { status, errorCount, warnCount } per phase. With errors it exits with a non-zero code; --allow-warnings exits 0 if only warnings remain. Additional flags: --fix (alias --write) canonicalizes the file in place (mints ids, normalizes branch tokens, repairs edge handles); --quiet only prints files that have errors or warnings; --out <path> saves the same JSON payload to disk in addition to stdout. --partial <file> runs the full validator on a single in-progress draft in preview mode: it returns rich diagnostics but never gates — it always exits 0 regardless of errors. As of v1.88, a validate-on-write hook runs this same preview automatically the moment an AI agent writes a workflow’s JSON, so diagnostics arrive immediately (they’re advisory only: they never block the write). Also as of v1.88, validate now validates tools/*.json files too (not just workflows/*.json) using the real tool-push rules, and it no longer incorrectly flags $output.set() inside a tool’s CODE node — that’s the correct way a tool returns a value.

`jelou test`

Test workflows locally: send messages, persist traces and chats, and inspect them.

Subcommand	Description
`tool <slug> --input k=v`	Executes a tool server-side and reports which output fired (in the CLI’s own `--help` output, `tool` now leads the list, ahead of `send`)
`send text --target <slug> --message "<txt>"`	Sends a message to a workflow and persists the trace
`turn status <execution-id> --target <slug>`	Long-polls an in-flight turn until it closes
`chats list --target <slug>`	Lists the recorded chats (executions)
`chats show <id> --target <slug>`	Detail of a chat (turns + rendered output)
`trace <execution-id> --target <slug>`	Inspects an execution’s trace
`grep <query> --target <slug>`	Full-text search across recorded user/assistant messages
`stats --target <slug>`	Aggregate counts, terminal-state breakdown, and `qa.db` storage size
`reset <execution-id> --target <slug>`	Clears the gateway-side cache for an execution so it reruns from the start
`cleanup --target <slug>`	Drops old `qa.db` runs per the retention policy
`dashboard`	Starts the local testing dashboard
`finish <execution-id> --target <slug>`	Marks a recorded run with a PASS/FAIL/INCONCLUSIVE verdict
`whatsapp <verb>`	Testing with a real WhatsApp account (experimental)

jelou test tool generar-otp --input identificacion=0912345678
jelou test send text --target saludo-web --message "hi"
jelou test send text --target saludo-web --execution <id> --message "next"
jelou test chats list --target saludo-web --terminal TIMEOUT --since 7d --json
jelou test trace sKI7morplA4LKUAX51Mqx --target saludo-web

AI cost per turn

Every time an AI Agent node replies, the output of jelou test send text and jelou test turn status includes a cost field with the tokens and the amount the turn consumed. There is one entry in items for each bubble that carried a cost, and that bubble’s rendered_chats row repeats it.

Cost field of a turn

"cost": {
  "total_tokens": 1234,
  "amount": 0.0031,
  "currency": "USD",
  "items": [
    {
      "node_id": "<AI Agent node id>",
      "node_title": "Agent",
      "execution_id": "<uuid>",
      "total_tokens": 1234,
      "amount": 0.0031,
      "currency": "USD"
    }
  ]
}

The amount is the price billed to your company, already calculated by the platform, just like in the Tester.

Value	When it appears
`cost: null`	No bubble in the turn carried a cost: the agent didn’t reply in that turn, or the turn closed without a realtime connection
`amount: null` and `currency: null`	The tokens are real, but some entry has no price (for example, a custom model) or the entries mix currencies

You don’t need to turn anything on in the node: the cost arrives on every test turn. The Show cost when testing on WhatsApp toggle only controls the footer on WhatsApp.

Local testing dashboard

jelou test dashboard            # opens the browser at http://127.0.0.1:8766
jelou test dashboard --port 9090
jelou test dashboard --repo otro-repo--abc123   # reads another repo's qa.db
jelou test dashboard --no-open

It brings up a single-URL local web interface (Hono server + React UI) to visually inspect your workflow tests — it’s the graphical version of what jelou test send text, jelou test chats list, and jelou test trace produce. What it shows:

Targets / workflows — the workflows you can test (those that have recorded runs, plus the ones in the lockfile even if they don’t have any yet).
Runs (test chats) — each recorded test conversation, with its turns, the rendered message, and its terminal status (STABLE, TIMEOUT, HARNESS_STALL, HARNESS_ERROR).
AI cost per turn — every AI Agent turn shows, below its last bubble, the turn’s tokens and cost, for example 1,234 tokens · $0.0031. If the model has no price, it shows only the tokens.
Per-node trace — for each run, the workflow’s step-by-step execution: each node with its initial and final state.

Internally it serves these read-only endpoints (/api/targets, /api/workflows, /api/runs, /api/runs/:id, /api/runs/:id/trace) and, if there’s a profile that can send messages, it lets you start new chats from the UI (POST /api/chats, /api/runs/:id/messages). What data it works with:

It reads the per-target qa.db files (SQLite) — the same ones the other jelou test commands create and query. There’s no separate database: the dashboard only visualizes them.
Data is isolated per repo (repo-id segment = git root directory name + a short hash) and per profile. That’s why you must run it inside the repo with your runs, or point it at another one with --repo <segment>.

Flag	Description
`--port <n>`	TCP port (default 8766; if it’s taken, uses a free one)
`--host <host>`	Host to bind to (must be loopback: `127.0.0.1`, `::1`, or `localhost`)
`--repo <segment>`	Reads another repo’s `qa.db` instead of the current one
`--open` / `--no-open`	Whether to open the browser automatically

It’s local-only (listens on loopback); for remote access use SSH port forwarding: ssh -L 8766:localhost:8766 <host>.

The BrainOps bundles jelou-build-workflow and jelou-test-workflow (skills) orchestrate this build-and-test cycle for workflows from an AI agent.

`jelou logs` — production conversation triage

Read-only access to a bot’s conversation history. It lets you drill down from conversation → chat timeline → the node that failed.

Subcommand	Description
`conversations list --bot-id <id>`	Lists conversations (one row per user × day)
`chat --bot-id <id> --user-id <phone>`	A user’s timeline (messages + executions)
`node --execution-id <id> --node-id <id>`	Debugs a single node execution

jelou logs conversations list --bot-id d42d688c-1c3f-4b99-9f32-70e14a10b365
jelou logs conversations list --bot-id d42d688c-… --message "return"
jelou logs chat --bot-id d42d688c-… --user-id 593959216623 --failed-only
jelou logs node --execution-id sKI7morplA4LKUAX51Mqx --node-id 69eb6c946b3d065a3bc6cc44

They all accept --from/--to (ISO-8601), --cursor for pagination, and --out <path> to save the JSON envelope. The --bot-id is the bot connected to the channel — discover it with jelou channels list. The drill-down flow prints the next command under each FAILED execution.

`jelou users reset`

Hard-resets a user’s cached state with a bot (clears the state, skill, and state_manual keys). Useful before re-testing from scratch or to unblock a user stuck in a loop.

jelou users reset --bot-id d42d688c-… --user-id 593959216623 --yes
jelou users reset --channel-id 01KR… --user-id 593959216623 --yes

It’s destructive: in-flight conversations lose their context. --bot-id and --channel-id are mutually exclusive; under --agent/--no-input, --yes is required.

Getting Started

Developer

Jelou CLI

Outbound Messaging

Inbox

Marketplace

Channels

Configuration

Billing

`jelou workflow`

`jelou test`

AI cost per turn

Local testing dashboard

`jelou logs` — production conversation triage

`jelou users reset`

​jelou workflow

​jelou test

​AI cost per turn

​Local testing dashboard

​jelou logs — production conversation triage

​jelou users reset

`jelou workflow`

`jelou test`

AI cost per turn

Local testing dashboard

`jelou logs` — production conversation triage

`jelou users reset`