TOOLS

localFloww CLI

Run Floww workflows from the terminal — headless, scriptable, CI/CD-ready.

localFloww is the command-line companion to the Floww desktop app. It executes .floww files without a GUI, making it ideal for automation, testing pipelines, and server-side execution. Every workflow you build visually on the canvas can be run identically from the terminal.

Installation

The fastest way to install localFloww is via npm:

npm install -g localfloww

Verify the installation:

localfloww --version

If you are on macOS or Linux, you can also use the install script:

curl -fsSL https://floww.pro/install.sh | sh

System requirements

Requirement	Minimum
Node.js (npm install)	v18 or later
Operating system	macOS 12+, Ubuntu 22.04+, Windows 10+
Memory	256 MB available RAM

The run Command

The run command executes a .floww file from start to finish. It resolves the DAG, runs each node in topological order, and streams output to stdout.

localfloww run project.floww

Exit codes

Code	Meaning
0	All nodes completed successfully
1	One or more nodes failed
2	File not found or invalid format
3	DAG cycle detected

Output capture

By default, node output is printed to stdout as it arrives. Use the --output flag to write structured results to a file:

localfloww run project.floww --output results.json

The results file contains each node's output, duration, and exit status in a machine-readable JSON array.

Selecting specific nodes

Run a single node (and its dependencies) with the --node flag:

localfloww run project.floww --node "Generate Summary"

The watch Command

The watch command monitors a .floww file and its referenced assets for changes, automatically re-executing the workflow on every save.

localfloww watch project.floww

This is especially useful during development: edit your workflow in the Floww desktop app and see results in the terminal in real time.

Options

Flag	Description
--debounce <ms>	Delay before re-running after a change (default: 300)
--clear	Clear the terminal before each run
--ignore <glob>	Ignore changes matching a glob pattern

The list Command

Inspect the contents of a .floww file without running it:

localfloww list project.floww

Sample output:

Nodes (5):
  1. Fetch Data         [http]        → 2
  2. Parse Response     [transform]   → 3, 4
  3. Summarize          [llm]         → 5
  4. Extract Keywords   [llm]         → 5
  5. Write Report       [file]

Workflows: 1
  main (5 nodes, 4 edges)

Filtering

List only nodes of a specific type:

localfloww list project.floww --type llm

Variable Injection

Workflows often need external values — API keys, file paths, or feature flags. localFloww supports three ways to inject variables at runtime.

Inline flags

Pass variables directly on the command line:

localfloww run project.floww --var api_key=sk-abc123 --var env=production

Environment variables

Any environment variable prefixed with FLOWW_ is automatically available inside nodes:

export FLOWW_API_KEY=sk-abc123
localfloww run project.floww

Inside a node, reference it as {{api_key}} (the FLOWW_ prefix is stripped).

.env file support

Place a .env file in the same directory as your .floww file. localFloww loads it automatically:

# .env
FLOWW_API_KEY=sk-abc123
FLOWW_MODEL=claude-sonnet-4-20250514
FLOWW_OUTPUT_DIR=./results

CI/CD Integration

localFloww's deterministic exit codes and JSON output make it straightforward to integrate into CI/CD pipelines.

GitHub Actions example

name: Run Floww Workflow
on: [push]

jobs:
  floww:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g localfloww
      - run: localfloww run workflows/pipeline.floww --output results.json
        env:
          FLOWW_API_KEY: ${{ secrets.API_KEY }}
      - uses: actions/upload-artifact@v4
        with:
          name: floww-results
          path: results.json

GitLab CI example

floww-pipeline:
  image: node:20
  stage: test
  script:
    - npm install -g localfloww
    - localfloww run workflows/pipeline.floww --output results.json
  variables:
    FLOWW_API_KEY: $API_KEY
  artifacts:
    paths:
      - results.json

.floww File Format

A .floww file is a JSON document that describes the complete state of a workflow. The desktop app reads and writes this format, and localFloww executes it.

Top-level structure

{
  "version": 1,
  "meta": {
    "name": "My Workflow",
    "created": "2025-11-15T10:30:00Z",
    "modified": "2025-11-16T14:22:00Z"
  },
  "nodes": [ ... ],
  "edges": [ ... ],
  "variables": { ... }
}

Node object

Each node represents a unit of work. Its type determines what it does — llm, http, transform, file, script, and so on.

{
  "id": "node_01",
  "type": "llm",
  "label": "Summarize",
  "config": {
    "model": "claude-sonnet-4-20250514",
    "prompt": "Summarize the following: {{input}}"
  },
  "position": { "x": 320, "y": 180 }
}

Edge object

Edges connect one node's output to another's input, forming the directed acyclic graph (DAG):

{
  "source": "node_01",
  "target": "node_02",
  "sourcePort": "output",
  "targetPort": "input"
}

How it maps to the canvas

Every visual element on the Floww canvas has a 1:1 mapping in the .floww file. Node positions correspond to canvas coordinates, edges correspond to the lines you draw between ports, and variables map to the values in the Variables panel. Editing the JSON directly is fully supported — changes appear instantly when you reopen the file in the desktop app.