Flows

A flow is a code-defined procedure that owns both the ordering of a multi-step operation and its mechanical details, so those details cannot be got wrong.

Publishing a workflow by hand means creating a parent record, building a version with matching node ids across definition and layout, wiring edge ports, and publishing — in the right order, with the right fields on every call. A flow does all of that from one spec. Prefer a flow over assembling the steps yourself.

Available flows

Flow	What it does	Mutates	Dry run
`publish-workflow`	Creates a workflow and a published version from one spec, atomically.	Yes	Yes
`revise-workflow`	Applies an edited spec to an existing workflow, honouring draft-then-publish automatically.	Yes	Yes
`export`	Writes an existing workflow back out as a spec, so edits are a round-trip rather than a patch.	No	No
`audit`	Produces a pre-publish readiness report for a workflow version.	No	No
`simulate`	Runs a workflow with one message and returns a normalized verdict instead of raw logs.	Yes	No
`diagnose`	Explains why a run behaved the way it did, from an execution id.	No	No

Run oneocto flow list for the current set. The list is generated from the CLI’s own registry, so it stays accurate across upgrades.

Discover a flow before running it

oneocto flow list                              # what flows exist
oneocto flow describe publish-workflow         # steps, spec schema, field guide, worked example
oneocto flow scaffold publish-workflow         # a valid starting spec, ready to edit

describe is the reference for a flow’s spec. scaffold gives you a spec that already validates, which is faster than writing one from the schema.

Publish a workflow

Generate a starting spec and save it to a file.
Edit the spec to describe the workflow you want.
Validate it offline with --dry-run.
Run the flow for real.

oneocto flow scaffold publish-workflow > workflow.json
oneocto flow publish-workflow --spec ./workflow.json --dry-run
oneocto flow publish-workflow --spec ./workflow.json

--dry-run validates the spec and reports what would be created without writing anything. Run it before every publish — it is the cheapest way to catch a malformed spec.

Revise an existing workflow

Editing is a round-trip, not a patch. Export the current state, edit the file, then apply it:

oneocto flow export <workflow-id> > workflow.json
oneocto flow revise-workflow <workflow-id> --spec ./workflow.json --dry-run
oneocto flow revise-workflow <workflow-id> --spec ./workflow.json

Published versions are immutable. When the latest version is already published, revise-workflow starts a draft for you, so immutability is not something you have to remember or work around.

Check a version before publishing

oneocto flow audit <workflow-version-id>

The audit is a readiness report: it looks over a version and reports what would stop it working once live. Run it against a draft before publishing rather than after.

Test and debug a run

oneocto flow simulate <workflow-id> -m 'I would like to book an appointment'
oneocto flow diagnose <execution-log-id>

simulate runs the workflow with one message and returns a normalized verdict rather than raw logs, so the result is readable without reconstructing the run by hand. Note that it genuinely executes the workflow — any tool the run reaches is really called.

diagnose explains a run after the fact: which node failed, what input it resolved to, and which references never resolved. Unresolved template references are the usual cause when a workflow runs but behaves unexpectedly.

Flow options

Option	Applies to	Description
`--spec <file>`	`publish-workflow`, `revise-workflow`	Path to the spec JSON file.
`--dry-run`	`publish-workflow`, `revise-workflow`	Validate and report what would change, without writing.
`-m`, `--message <text>`	`simulate`	The user message to simulate with.
`--tenant <slug>`	All except `list`, `describe`, `scaffold`	Tenant slug override.
`--space-id <id>`	All except `list`, `describe`, `scaffold`	Space id override.

list, describe, and scaffold read from the CLI’s own registry, so they work offline and need no tenant.

FAQ

Why use a flow instead of the individual commands? Because the mechanical details — node ids, canvas layout, edge port wiring, publish-time fields — are handled for you. Those are the parts that are easy to get subtly wrong when hand-sequencing commands.

How do I see the options for one flow? Use the help verb: oneocto flow help publish-workflow. A trailing --help on a nested command falls back to top-level help.

Does simulate cost anything? It runs the workflow for real, so model usage and any tools the run reaches are real. Treat it as a live run against a test workflow, not as an offline check.

Which id does diagnose want? An execution log id. Find one with oneocto list workflow-execution-logs filtered to the workflow you are investigating.

Command Reference - the verbs and options flows build on
Versions and Publishing - the draft and publish model flows follow
Testing and Debugging - the same work from the console
Using the CLI from an Agent - authoring rules for agents building workflows