🌀 Nexss Flow

Nexss Flow is a Go runtime and language for composing .nflow programs from registered actions. The nflow CLI runs flows and inspects the active compiler surface.

Install

Requires Go 1.26 or later. Install the CLI from the current main branch:

go install github.com/nexssp/flow/cmd/nflow@main 🌀
nflow version

Make sure Go's binary directory ($(go env GOBIN), or $(go env GOPATH)/bin when GOBIN is unset) is on your PATH.

Quick start

nflow help
nflow lint examples/00_flow_basics/04_data_transformation.nflow
nflow lint ./examples/...
nflow run examples/00_flow_basics/04_data_transformation.nflow

The example projects a nested value into a new shape and prints:

{
  "id": 101,
  "name": "Maksymilian",
  "status": "active",
  "summary": "Maksymilian (ID: 101) is active"
}

Examples

The introductory flows are checked by CI: each one must pass nflow lint and run successfully from the repository root.

• Logging and debug
• Timeout and fallback
• Dynamic dispatch
• Data transformation
• Error fallback
• Parallel actions

Run the complete set locally with task examples or run an individual flow with nflow run <file.nflow>.

Integrated specifications

The root spec/ suite contains deterministic, real-world workflows that combine extensions with scenario-local custom bundles. It covers order intake, support triage and safe recovery, and payment reconciliation. Run it with task specs; task test and task ci also run every extension's categorized NFlow conformance suite.

Verify without running a flow 🌀

Use nflow lint <file.nflow> for a static check, or pass a directory or Go-style recursive target such as nflow lint ./examples/... to discover sources automatically. It preprocesses each file, parses its pipeline, and checks referenced atoms and modifiers against that file's active registry; it does not execute flows. Recursive discovery sorts paths, skips .git, .hg, .svn, vendor, and node_modules, and does not follow symlinks. Lint is not a substitute for exercising runtime behavior, and it does not prove every expression or input will succeed. The broader nflow lint ./... also discovers internal developer sources and extension fixtures, some of which currently produce context-specific diagnostics; CI intentionally scopes its lint gate to ./examples/....

The similarly named build commands do different jobs:

• nflow build -o ./bin/my-flow examples/00_flow_basics/04_data_transformation.nflow creates a standalone executable with the flow embedded. It is a packaging/build command, not a check-only validator; the flow runs when you launch the generated executable. Put -o before the input path with the current CLI parser. nflow help build currently advertises --target, but this checkout's implementation does not parse that flag; the command above uses the supported -o option.
• go build ./... compiles the repository's Go packages. It does not validate or execute .nflow files.
• go test ./... runs the repository's Go tests, including tests that may exercise Flow features. For a no-runtime-execution check of a particular flow, use nflow lint; for repository code verification, use go test ./....

Documentation

• Language syntax and directives
• Symbol namespaces and single-source values
• CLI and runtime
• Extension bundles
• Integrated specifications
• Practical secure-pipeline examples
• Editor setup for VS Code and Zed

Microkernel and extensions

Nexss Flow uses a microkernel-style design: compiler.Bundle is the contract through which bundles contribute action libraries and compiler extensions. The CLI assembles its built-in bundles, while @require can load a bundle for a flow; a package's presence under extensions/ alone does not enable it. See the extension guide for the current bundle model.