Flow is a lightweight YAML DSL that lets developers define portable, executable workflow graphs for seamless automation across tools and platforms.

In a world of fragmented automation tools, Flow stands out as the elegant YAML-based Domain-Specific Language (DSL) for serializing workflow graphs. Whether you're building event-driven orchestrators, integrating APIs, or scaling computational pipelines, Flow's node-and-edge structure provides a clean, interoperable way to define triggers, actions, decisions, and loops—all while ensuring safety with bounds, timeouts, and error handling. Designed for developers who demand simplicity without sacrificing power, it supports Turing-complete expressiveness through composable primitives, making it perfect for cross-tool portability and innovation in agentic workflows. Say goodbye to proprietary formats and hello to graphs that truly flow.

check this out

screencast.mp4

Flow requires Bun runtime for execution.

# Install Bun (if not already installed)
curl -fsSL https://bun.sh/install | bash

# Clone and setup Flow
git clone https://github.com/mikesmullin/flow.git
cd flow
bun link

# Verify installation
flow version

Create your first workflow file hello.flow.yaml:

version: "2.0"
id: "hello-world"
label: "Hello World Workflow"

nodes:
  - id: start
    type: trigger
    params:
      event: "manual"
  
  - id: greet
    type: action
    params:
      task: "log"
      message: "Hello, Flow! 🌊"
  
  - id: end
    type: end
    params:
      output: "Workflow completed successfully"

edges:
  - from: start
    to: greet
  - from: greet
    to: end

entrypoints: ["start"]

Execute your workflow:

flow hello.flow.yaml

Build responsive workflows triggered by HTTP webhooks, file changes, or timers:

# Process incoming webhook data
flow webhook-processor.flow.yaml

# Watch for file changes and process
flow file-watcher.flow.yaml --debug

Create ETL workflows with transformation steps and error handling:

# Transform CSV data with validation
flow data-pipeline.flow.yaml --format json

# Batch process with parallel execution
flow batch-processor.flow.yaml

Implement branching logic based on dynamic conditions:

# Route based on input validation
flow conditional-router.flow.yaml

# Multi-stage approval process
flow approval-workflow.flow.yaml

Execute concurrent tasks with synchronization points:

# Parallel API calls with join
flow parallel-api.flow.yaml

# Concurrent data processing
flow parallel-transform.flow.yaml

Handle batch processing and retry logic:

# Process items with bounded iteration
flow batch-loop.flow.yaml

# Retry with exponential backoff
flow retry-workflow.flow.yaml

For more complete examples, see the integration test fixtures.

The flow browse command launches an interactive web-based graph editor and executor:

• Real-time Visualization: Live workflow execution with animated node traversal and state updates
• Interactive Editing: Drag-and-drop node placement, visual edge creation, and property editing
• Hot Reload: Automatic file watching with instant browser updates when workflows change
• Execution Monitoring: Debug panel with live logs, state inspection, and performance metrics
• Multi-format Export: Save workflows with preserved layout and fork existing workflows
• Cross-platform: Works on any modern browser with WebSocket support for real-time updates
• Performance Optimized: 60fps canvas rendering with efficient memory management
• Developer Tools: Console logging, error handling, and HiDPI display support

flow browse my-workflow.flow.yaml --port 8080

Flow executes .flow.yaml files following the WGN v2.0 specification. Each workflow requires:

• version: "2.0" (required)
• nodes: Array of workflow nodes with unique IDs and types
• edges: Array defining connections between nodes
• entrypoints: Array of node IDs where execution begins

• trigger: Event sources (manual, HTTP, timer, file)
• action: Executable tasks (shell commands, JavaScript, logging)
• decision: Conditional branching with true/false paths
• loop: Iteration with condition or range bounds
• parallel: Concurrent execution with join strategies
• end: Workflow termination with final output

• ${expression}: JavaScript expressions with access to state and inputs
• $(command): Bash command execution with output capture

For the complete specification, see RFC_0002.md.

# Execute workflow
flow my-workflow.flow.yaml

# Validate syntax
flow validate my-workflow.flow.yaml

# Visual editor
flow browse my-workflow.flow.yaml

# Output formats
flow my-workflow.flow.yaml --format json
flow my-workflow.flow.yaml --format yaml

# Debug mode
flow my-workflow.flow.yaml --debug

# Show help
flow help

Use flow help for complete command documentation and options.

# Run tests
bun test

# Integration tests
bun test:integration

# Development mode
bun dev help

• src/cli/ - Command-line interface and help system
• src/core/ - Workflow parser, executor, and graph engine
• src/nodes/ - Node type implementations (action, decision, etc.)
• src/frontend/ - Web-based visual browser
• src/utils/ - Shared utilities and error handling
• tests/ - Unit and integration test suites

• Workflow Graph Notation (WGN) - complete DSL specification