NEXSS FLOW · GETTING STARTED
5 min read | Updated 2026-10-01
All docs
NF
Docs getting-started
SEARCHABLE · DATA-DRIVEN
Getting Started

Getting Started with Nexss Flow

Install the nflow CLI from main, lint the canonical example, run it, and build a standalone binary in under five minutes.

Nexss 5 min read Updated 2026-10-01
installclilintrunbuild

Install the CLI

Nexss Flow ships as a single Go binary. No daemon, no scheduler, no database.

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

bash bash
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. Verify the install with nflow version — it should print build metadata (version, commit, built at).

No Go installed?
Pre-built binaries for Linux, macOS, and Windows are published on the GitHub releases page. Download, chmod +x, and add to your PATH. The CLI is a single static binary with no runtime dependencies.

Lint a flow without executing it

Use nflow lint to verify preprocessing, parsing, and known atom/modifier names against the active registry — without executing the flow.

bash bash
nflow lint examples/00_flow_basics/04_data_transformation.nflow
nflow lint ./examples/...      # recursive discovery
nflow lint ./...               # all sources (includes dev fixtures)

Lint accepts a file, an exact directory, or a Go-style ./... / ./path/... target. Multiple file, directory, and recursive targets may be supplied together. Discovery is deterministic, skips VCS metadata directories (.git, .hg, .svn), vendored dependencies (vendor), and node_modules. It does not follow symlinked directories and skips symlinked files during discovery.

Lint is not a runtime check
Lint checks preprocessing, parsing, and known atom/modifier names — not runtime input values, security properties, or every possible expression. An all-valid batch prints ok (N files). Batch failures return one JSON diagnostics array covering the discovered sources that failed.

Run a flow

Run accepts a .nflow path and an optional JSON payload. Its documented flags include -v/-vv/-vvv for verbosity and --assert=EXPR for a post-run result check.

bash bash
nflow run examples/00_flow_basics/04_data_transformation.nflow
nflow run examples/00_flow_basics/04_data_transformation.nflow \
  --assert='result.id == 101'
nflow run -vv flows/client.nflow

The example projects a nested value into a new shape. When you run 04_data_transformation.nflow, it prints the JSON object below — the projection combined nested fields with a string-concatenation expression.

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

Build a standalone executable

The same source compiles to a self-contained executable with the .nflow source, declared transports, and @require modules embedded.

bash bash
nflow build -o ./bin/my-flow examples/00_flow_basics/04_data_transformation.nflow
./bin/my-flow    # runs without the CLI

Put -o FILE before the input path. The current build parser stops reading flags when it reaches the positional path, so putting -o after the path does not select the requested output. The resulting binary has zero runtime dependencies — deploy with FROM scratch.

No cross-compilation flag
nflow build currently targets the host platform. It does not provide a --target cross-compilation flag; the online help text advertising --target is stale. For cross-compilation, build the generated Go harness with the required GOOS and GOARCH values.

Where to go next