Running Flows

A flow is callable identically from a human, from a script, and from an AI agent. All three paths share the same typed signature and return the same shape.

From the zen CLI

The zen CLI forwards to a configured server or a local installation:

zen run-flow hello -p message="Hi there"

See The zen CLI for the full command surface.

From any HTTP client

A POST to the flow’s run endpoint. live is the branch alias that resolves to production on Git-disabled installs:

curl -X POST http://localhost:5000/api/v1/live/flows/hello/runs \
  -H "Content-Type: application/json" \
  -d '{"message":"Hi there"}'

On a Git-enabled install, replace live with your branch name (e.g. main, edi-rework). The full URL family rules are in API Surfaces.

The two selectors are independent: the branch segment in the URL picks which version of the definitions runs, while --env / on= picks which systems the run talks to. See Environments vs Branches.

From an MCP-aware assistant

MCP — the Model Context Protocol — is the open standard AI assistants use to discover and invoke tools. From Claude Code, VS Code, or any MCP client, call the run-flow tool:

{ "flow": "hello", "parameters": { "message": "Hi there" } }

The assistant sees the flow’s typed signature through the same metadata the type provider uses, so it can autocomplete the parameters. The same MCP channel reaches read-entity, list-entities, and the connector catalog, so an assistant can run small experiments against your installation as part of diagnosing a problem.

The same shape, every path

The CLI’s run-flow command and MCP’s run-flow tool are synchronous — they wait for the flow and hand back the typed output directly:

{
  "echo": "Parameters received successfully",
  "message": "Hi there"
}

The REST call above is different: flows run asynchronously by default, so POST .../runs hands back a run id as plain text, not the typed output — see Your First Flow for the exact response and the synchronous REST alternative (POST .../cicd/run-flow with "wait":true). Once you’re past that async/sync distinction, the equivalence is on purpose: the typed output: contract is what makes a flow callable from REST, MCP, the CLI, and other flows with the same guarantees.

Reading run results and logs

Each run gets its own UUIDv7 ID, its own log stream, and its own output. Read them after the fact:

• CLI: zen logs <run-id> (supports live tailing).
• REST: the runs verbs under /api/v1/{branch}/runs.
• MCP: read-entity entity=run and the runs:///introspection read resource.

Runs are independent and can run in parallel.