Skip to content
Flow Docs
Flow home Back to the main Flow site

Your first flow

This walkthrough builds the most common flow shape, a linear chain with a failure branch. You build it twice. The first time you build it on the Flow Studio canvas. The second time you write it as Flow DSL text that you can run headlessly with the CLI.

The flow

Section titled “The flow”

Install dependencies, build the project, and run the tests. If the tests fail, have a local model triage the output:

flow "first-flow" v1


deps[action: "Install"] {
  adapter: "shell"
  actionId: "pnpm"
  args: "install"
}


build[action: "Build"] {
  adapter: "shell"
  actionId: "pnpm"
  args: "build"
}


test[action: "Test"] {
  adapter: "shell"
  actionId: "cargo"
  args: "test --workspace"
}


triage[ai: "Triage failure"] {
  modelId: "local-llm"
  input: "The test suite failed. Summarise the root cause in two sentences."
}


deps --> build
build --> test
test.fail --> triage

This flow has four nodes and three edges. The test.fail edge only fires when the test step fails. On a green run, triage never executes and the local model never loads.

On the canvas

Section titled “On the canvas”

  1. Open Flow Studio and create a new flow tab.

  2. Drag two Shell action nodes from the Library panel onto the canvas. In the inspector, set the first to action pnpm with args install, the second to pnpm with args build.

  3. Add a third Shell node with action cargo and args test --workspace.

  4. Connect the nodes. Drag from each node’s output port to the next node’s input. A plain connection routes on always. Drag from the green diamond for pass or the red diamond for fail.

  5. Drag an AI node onto the canvas, leave the provider as local, pick a model you’ve loaded from the Model Hub, and write the triage prompt. Connect it from the test node’s fail port.

  6. Press Run. Pre-run validation checks every action node’s required fields first. A missing field blocks the run and focuses the offending node. Watch the nodes light up as they execute. Output streams to the bottom Logs panel, and the run lands in History.

Headless, with the CLI

Section titled “Headless, with the CLI”

Save the DSL above as first.flow and:

Terminal window
flow validate first.flow     # parse + static checks
flow run first.flow          # run with live per-node streaming
flow run first.flow --json   # NDJSON event stream for CI

The CLI records the run into the same SQLite history the desktop reads. Open Flow Studio’s History view and the headless run is there.

What you just used

Section titled “What you just used”
  • Outcome routing. The pass, fail, and always edges are the control flow. You do not write conditionals. The engine routes on each node’s outcome.
  • Pre-run validation. Required adapter fields are checked before anything executes.
  • Local AI on the failure path. The model only runs when there is something to interpret, and the inference never leaves your machine.
  • One graph, two surfaces. The canvas and the DSL are two views of the same execution graph.

Next steps

Section titled “Next steps”