🌀 Nexss Flow

Runnable examples are maintained in the central Nexss Ecosystem Examples repository.

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.

Use nflow fmt to format Flow source from the CLI or an editor; use nflow lint when you need full preprocessed, registry-aware validation. See the CLI guide for formatter modes and safety behavior.

Install

Prebuilt CLI downloads are published on GitHub Releases for Linux, macOS, and Windows (amd64 and arm64), with SHA-256 checksums. See CLI releases for archive details and publishing instructions.

Install the latest prebuilt release without Go on Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/nexssp/flow/main/install.sh | sh

On Windows, download and run the PowerShell installer; it verifies the archive and adds the per-user install directory to PATH:

Invoke-WebRequest https://raw.githubusercontent.com/nexssp/flow/main/install.ps1 -OutFile install.ps1
powershell -ExecutionPolicy Bypass -File .\install.ps1

Both installers accept a pinned version; see installer options.

Alternatively, install the CLI with Go:

go install github.com/nexssp/flow/cmd/nflow@latest
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

From the central examples checkout:

git clone https://github.com/nexssp/examples.git
cd examples
nflow lint flow/00_flow_basics/04_data_transformation.nflow
nflow run flow/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"
}

Recommended syntax

Write new flows with the current composable syntax: pipeline operators such as ->, projections such as { id, name: .customer.name }, and structured action arguments such as @{ order_id: .order_id }. The older action(key=value, ...) form is kept only for compatibility with existing flows; do not use it as the pattern for new code. See the syntax walkthrough and language reference.

Examples

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

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

Run the complete set locally with task examples:nflow from the central examples repository, 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 its static lint gate with task lint:nflow and execute its assertions with nflow test ./spec (or task test:nflow). The existing task specs target remains available and CI continues to run it. task test runs Go tests, including native extension conformance and the host-root embed fixture, but not integrated scenarios. See focused syntax checks for a smaller verification scope.

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 ./flow/... 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. Lint is not a substitute for exercising runtime behavior, and it does not prove every expression or input will succeed.

For local performance measurements, use nflow self bench; it compiles and runs the bundled benchmark scenarios in-process, with warmup excluded from the reported timings. This is separate from nflow self test, which checks feature correctness. See the CLI guide for filters, custom scenario paths, metrics, and safety details.

The similarly named build commands do different jobs:

• nflow build -o ./bin/my-flow flow/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. Build flags may precede or follow the input path; use nflow help build for supported options.
• task build compiles the repository's Go packages. It does not validate or execute .nflow files.
• task test runs the repository's short test suite. Use task test -- ./runner to target a package, task test:race for race detection, and task ci for the complete repository gate.

Repository workflows

All local verification goes through Task, matching CI:

task --list
task test
task test -- ./runner
task lint:nflow
task test:nflow
task test:smoke
task bench
task ci

Documentation

• Flow language and runtime reference — implementation-backed syntax, validation, runtime, extensions, and CLI boundaries
• Language syntax walkthrough
• Symbol namespaces and single-source values
• CLI and runtime
• Managing requirements
• Extension bundles
• Durable runner execution
• Approval pause and resume
• Resilience policies
• Error recovery
• Schemas and validation and runtime validation
• 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.