NEXSS FLOW · REFERENCE

8 min read | Updated 2026-10-01

Reference

nflow CLI Reference

Every nflow command: init, run, build, serve, lint, list, show, info, catalog, self, completion, version. Usage, flags, and examples for each.

Nexss 8 min read Updated 2026-10-01

clireferencecommandsflags

Commands at a glance

The CLI is built in this repository as ./cmd/nflow. The commands below use go run from the repository root; after installing the CLI, the same arguments can be passed directly to nflow.

nflow init [project_dir] [--bundle [folder]] — initialize a project or scaffold a nexssflow extension bundle.
nflow run <file.nflow> [json_payload] [flags] — compile and execute a .nflow file. Builds or reuses a harness binary when the file declares @require.
nflow build <file.nflow> -o <output> [flags] — compile a .nflow file into a standalone executable.
nflow serve <file.nflow> — run a .nflow file as a long-running daemon. The file must declare @on event.
nflow lint <file.nflow | directory | ./...> — check sources against the live registry; exits 1 and prints JSON issues on failure.
nflow list [pattern] [--flow FILE] [--json] [--no-color] — list every atom, modifier, directive, and operator known to the compiler.
nflow show <name> [--flow FILE] [--no-color] — show details for one atom, modifier, directive, or operator.
nflow info <file.nflow> — describe a .nflow pipeline without executing it (alias for nflow run --info).
nflow catalog [--flow FILE] — dump the compiler surface (atoms, modifiers, directives, operators) as JSON.
nflow self <up|test> [filter...] — manage the installed nflow binary, or run the embedded feature coverage suite.
nflow completion <bash|zsh|pwsh> — print a shell completion script.
nflow version — print build metadata (version, commit, built at).

nflow run

Compile and execute a .nflow file in one step. Builds or reuses a harness binary when the file declares @require.

bash bash

nflow run flows/client.nflow '{"user_id": 42}'
nflow run flows/client.nflow --assert='result.ok == true'
nflow run -vv flows/client.nflow
nflow run --info flows/client.nflow

-v | -vv | -vvv — verbosity.
--assert=EXPR — assertion evaluated after the run.
--info — describe the pipeline instead of executing.

nflow build currently targets the host platform. It does not provide a --target cross-compilation flag. For cross-compilation, build the generated Go harness with the required GOOS and GOARCH values.

nflow lint

Check .nflow sources against the live registry. Exits 1 and prints JSON issues on failure.

bash bash

nflow lint flows/client.nflow
nflow lint ./...
nflow lint ./examples/...

Pass a file to retain the single-file check, an exact directory to check its sources recursively, or a Go-style ./... / ./path/... target. Multiple file, directory, and recursive targets may be supplied together. Quote or otherwise pass ./... as a literal argument; shells do not expand this pattern.

Directory discovery checks .nflow files in deterministic path order. It skips VCS metadata directories (.git, .hg, .svn), vendored dependencies (vendor), and installed JavaScript dependencies (node_modules). It does not follow symlinked directories and skips symlinked files during discovery, avoiding loops and duplicate paths. A direct single-file argument may still name a symlink. If a selected directory contains no .nflow files, lint reports that explicitly and exits nonzero.

CI scoping

Use nflow lint ./examples/... to check every user-facing .nflow example; CI uses this scoped command. The broader nflow lint ./... also discovers internal developer sources under nflows/ and extension test fixtures. Some of those files currently produce context-specific parse or registry diagnostics, so a full-tree failure does not imply that the user-facing examples failed.

nflow list · nflow show · nflow catalog

Three commands for inspecting the active compiler surface.

bash bash

nflow list
nflow list fs
nflow list --json > catalog.json
nflow show fs.walk
nflow catalog > catalog.json
nflow catalog --flow flows/client.nflow > catalog.json

list displays known atoms, modifiers, directives, and operators; accepts a search pattern and supports --json.
show prints details for one catalog entry.
catalog emits the compiler surface as JSON.

nflow self

Manage the installed nflow binary, or run the embedded feature coverage suite.

bash bash

nflow self up                        # rebuild with VCS metadata from source tree
nflow self test                      # run the whole coverage suite
nflow self test operators            # only features in the Operators section
nflow self test loop assert          # anything matching "loop" OR "assert"

--verbose — print DSL on failure.
--json — machine-readable JSON summary.
--no-color — disable ANSI color.

nflow init

Initialize a new Nexss Flow project, or scaffold a nexssflow extension bundle.

bash bash

nflow init                      # initialize starter project in current directory
nflow init my-project           # initialize starter project in new directory
nflow init --bundle             # scaffold ./nexssflow/library.go in current repo
nflow init --bundle nexssflow_dev  # scaffold custom extension folder

nflow serve

Run a .nflow file as a long-running daemon. The file must declare `@on event`.

bash bash

nflow serve flows/api.nflow

Environment variables

Logging is controlled via standard slog environment variables. Set them per-invocation or in your shell profile.

LOG_LEVEL=debug|warn|error — control verbosity (default: info).
LOG_FORMAT=json — emit JSON-structured logs instead of text.

bash bash

LOG_LEVEL=debug LOG_FORMAT=json nflow run flows/client.nflow