FlowWrightDocs
Back to siteGitHub
Documentation · pre-release

Pipelines you can read like code.

FlowWright is a local-first, TypeScript-native pipeline engine. Author one typed pipeline.ts and run it on your laptop, inside your existing CI, or on a server you host.

Get startedBrowse all sections
  • MIT licensed
  • Node 24+
  • No YAML
  • Self-hosted
localhost:4317 — acme-api #10
A FlowWright run detail page: five stages, four succeeded and the fifth still running, with the run's log output streaming below.A FlowWright run detail page: five stages, four succeeded and the fifth still running, with the run's log output streaming below.

Start here

three paths through the same engine
01 · Run it locally

Your first pipeline

Install the CLI, scaffold from the package scripts you already have, and watch a run stream in your terminal.

→ Requirements & install→ flow init→ flow run02 · Understand it

How the model works

How a pipeline.ts becomes an execution plan, and who is allowed to run one.

→ Architecture→ Local vs. server→ The plan contract03 · Operate it

Host it yourself

One image, two daemons. Bring up the server and a worker pool, then keep the record.

→ Docker Compose→ Authentication→ Operations

Every section

56 pages · English

Quickstart

1 page

Install the CLI and run your first pipeline.

Concepts

2 pages

How a pipeline.ts becomes a plan, and who is allowed to run it.

The flow CLI

6 pages

Every command, flag and exit code.

Authoring pipelines

9 pages

The pipeline.ts DSL, end to end.

Plugins

8 pages

Seven shared libraries of stage helpers.

Running in CI

4 pages

FlowWright as the body of your existing CI job.

Self-hosting

7 pages

One image, two daemons — server and workers.

Control plane

12 pages

Using the server's web app — workspaces, projects, runs and administration.

Reference

6 pages

Flat lookup tables for the five stable surfaces.

Authoring

A stage is a function. Nothing more.

Dependencies, matrices, conditions, containers and caches are all typed arguments — so your editor autocompletes your pipeline and tsc catches the mistake before a runner does.

  • Real control flow — needs, when and matrix expansion, in TypeScript.
  • The same file runs locally, in GitHub Actions, GitLab CI or Jenkins.
  • Every run emits a typed event stream you can replay and audit.
Read the authoring guide
pipeline.ts
import { pipeline, stage, sh } from "@flowwright/core";

export default pipeline({
  name: "acme-api",
  stages: [
    stage("Install", async () => {
      await sh(["npm", "ci"]);
    }),
    stage("Test", {
      needs: ["install"],
      run: async () => {
        await sh(["npm", "test"]);
      },
    }),
  ],
});
flow explain
Pipeline: acme-api

  install
      $ npm ci
  test ← install
      $ npm test

Official plugins

Plugin overview →
@flowwright/plugin-stdWorkspace housekeeping, plus the stash and checkout helpers.@flowwright/plugin-gitClone, checkout, tag and push — with a ready-made checkout stage.@flowwright/plugin-nodeA whole Node CI lifecycle as composable stages.@flowwright/plugin-pythonpip, uv and poetry — install, ruff, mypy, pytest, publish.@flowwright/plugin-dockerBuild, tag and push images, with login as its own stage.@flowwright/plugin-cacheRestore/save around a stage body, keyed by a content hash.@flowwright/plugin-artifactsDeclare build outputs, as a helper or an archive stage.
Reference

Flat lookup tables, no prose.

Five surfaces we keep stable across minor versions — and a CI check that fails when the engine adds an event or an error code that no page describes.

01CLI flagsEvery flag, environment variable and exit code.02Execution planThe JSON contract between the CLI, the server and a worker.03EventsThe twelve execution events behind --reporter json.04Validation errorsEvery code flow validate can print, and the fix for each.05PermissionsAll twenty-one, and what each one gates.

The control plane you host

server · workers · audit trail
The FlowWright workspace overview: success rate and duration tiles, a list of recent runs, and the projects behind them.The FlowWright workspace overview: success rate and duration tiles, a list of recent runs, and the projects behind them.
Every project, every run, one page.
The FlowWright worker fleet: two online workers with their load, labels and capabilities, each with a drain control.The FlowWright worker fleet: two online workers with their load, labels and capabilities, each with a drain control.
Capacity, labels and drain across the colony.
  1. flow CLIbuilds the plan
  2. Servervalidates, applies policy, queues
  3. Workerclaims it and runs the stages
How a plan travels from CLI to worker.

Five minutes to your first green run.

No account, no server, no YAML — just Node 24 and a project you already have.

Run the quickstart