Flows

A flow is automation written as a list of named steps. You describe what should happen; the engine works out the order, checks it, runs it, and remembers where it got to.

name: hello
tasks:
  - name: greet
    shell: |
      echo "Hello from a flow"

kis flow -f hello.yaml

>> Workers: 1
>> Flow: hello.yaml execution started at 2026-08-05T11:31:13Z
Hello from a flow
execution engine instance Status: completed Completed Nodes: [greet]
>> Flow: hello.yaml executed in 1.00s

That last line before the timing is worth reading: the engine reports which nodes completed. It is the smallest example of the thing a flow gives you and a script does not — a record of position.

The four ideas

Everything else is detail on top of these.

A node is a unit of work. Each entry under tasks: is a node. It has a name, one atom (shell:, s3:, db: …), the parameters for it, and optionally where to go next. Nodes are also the unit of failure, of retry, and of the record the engine keeps.

Planning happens first. Before the first node runs, the engine reads the whole definition, resolves every task name against the registry, and validates parameters. A misspelled task or a missing required field fails the run immediately rather than forty minutes in.

Variables are the run’s memory. A node writes into the run with setvar: or assign:, later nodes read it back with {{name}}. This is how work passes between steps.

Position is durable. The engine records each node’s outcome as it goes. That is what makes a run resumable, what lets a lost worker be replaced mid-run, and what lets you rerun only part of a flow.

Running one

kis flow -f build.yaml                        # run it
kis flow -f build.yaml -w 4                   # four workers, for parallel nodes
kis flow -f build.yaml -v env=staging         # set a variable
kis flow -f build.yaml -e prod.yaml           # load variables from a file
kis flow -f build.yaml -s compile             # start at a named node
kis flow -f build.yaml -t compile,test        # run only these nodes
kis flow -f build.yaml -d                     # dry run

kis automate is an accepted alias for kis flow; they are the same command.

Two of these earn their keep during development. -t runs a subset, so you can exercise one node without the twenty before it. -d plans without executing, which is the quickest way to find out whether a definition is valid.

Flag	Effect
-f, --flow	The flow file. Required
-w, --workers	Worker count. Parallel nodes need at least as many workers as their concurrency
-v, --vars	Set variables, k=v, repeatable
-e, --env	Load variables from a YAML file
-n, --name	Which flow to run, in a file that declares several
-s, --start	Begin at a named node instead of the first
-t, --tasks	Run only the named nodes
-d, --dryrun	Plan and validate; do not execute
--pin-agent	Run every node on one worker
--affinity	single-agent, definition or payload
--affinity-key	Payload fields that decide the binding
--restart-on-failure	On losing a worker, restart the run rather than resume it
--logfile	Write the run log to a file

What is in this section

Page	Covers
The flow file	Top-level keys, variables, tables, imports, templating
Node types	Task, assign, choice, foreach, map, wait, subflow, fail, succeed
Execution	Planning, workers, retries, failure routing, affinity, resume
Flow engines	Automate, AI Flow, Workflows and Datapipes, and what each can call

For the atoms a node can run, see the atom reference. For when a script is the better tool, see Flows and scripts.