Nodes Reference

All 46 built-in nodes across 9 categories.

Every node has pins: exec pins (white diamonds) control flow order, data pins (colored circles) carry typed values. Drag pin to pin to wire them. Drag a pin to empty canvas to create a compatible node automatically.

CLI Reference

Run flows headlessly and compile them to standalone binaries.

The release archive contains the CLI binary twistedflow-cli, but the recommended install name is twistedflow. It shares the same Rust runtime and builder crates as the desktop app. Download it from GitHub Releases (twistedflow-cli-<platform>.tar.gz) and install:

# macOS Apple Silicon
tar -xzf twistedflow-cli-aarch64-apple-darwin.tar.gz
sudo mv twistedflow-cli /usr/local/bin/twistedflow

twistedflow run

Run a .flow.json file headlessly.

twistedflow run <file> [options]

Examples

# Basic run
twistedflow run ./flows/main.flow.json

# With env vars
twistedflow run ./flows/main.flow.json -e API_KEY=abc123 -e BASE_URL=https://api.example.com

# Pass arguments to the flow (ParseArgs node reads these)
twistedflow run ./flows/my-tool.flow.json -- --input data.json --verbose

# Pipe data into a flow (Stdin node reads this)
cat urls.txt | twistedflow run ./flows/check-urls.flow.json

# With base URL and quiet mode
twistedflow run ./flows/health-check.flow.json --base-url https://api.example.com -q

Output

Node status is printed to stderr. Log/Print node output goes to stdout. This means you can pipe flow output:

twistedflow run ./flows/transform.flow.json | jq '.result'

twistedflow build

Compile a project into a standalone binary. The binary embeds the flow JSON and environment variables — just run it, no arguments needed.

twistedflow build <project> [options]

Examples

# Build with defaults
twistedflow build ~/my-project -o my-app

# Build specific flow with prod env
twistedflow build ~/my-project -o health-checker --flow health-check --env prod

# Build optimized release binary
twistedflow build ~/my-project -o my-app --release

# Run the compiled binary
./my-app

Exit codes

Custom Nodes

Extend TwistedFlow with project-local custom nodes written in Rust and compiled to WASM. Author them from the desktop app or the CLI.

How it works

TwistedFlow uses wasmtime to load WebAssembly modules as custom node types. Plugins appear in the node palette alongside built-in nodes, with no runtime performance penalty vs built-in Rust nodes for most workloads.

Project-local layout

Custom nodes are project assets. TwistedFlow loads built .wasm files from the current project's nodes/ directory. Editable Rust source lives in nodes-src/.

Quick start from CLI

Three commands from an empty directory to an installed custom node:

twistedflow plugin new my-plugin --category Utility --node Hello
# edit my-plugin/src/lib.rs
cd my-plugin
twistedflow plugin build

The plugin new command scaffolds a complete Rust crate. The plugin build command compiles to wasm32-wasip1, validates the output, and installs into the nearest parent TwistedFlow project's nodes/ directory by default.

Desktop authoring

1. Open a project
2. Open the Custom Nodes tab in the bottom workspace
3. Click New Node
4. Edit the generated Rust source in your editor
5. Click Build Plugin on the node tile

The desktop app writes source under <project>/nodes-src/ and installs validated artifacts into <project>/nodes/.

The nodes! macro

Declare one or more nodes in a single nodes! { ... } block:

use twistedflow_plugin::*;

nodes! {
    node "Uppercase" (
        type_id = "uppercase",
        category = "Text"
    ) {
        inputs:  [{ key: "text",   data_type: "string" }],
        outputs: [{ key: "result", data_type: "string" }],
        execute: |inputs| {
            let text = inputs.get_string("text").unwrap_or_default();
            PluginOutputs::new().set("result", text.to_uppercase())
        }
    }
}

Pin types

Host callbacks

Plugins can call back into TwistedFlow. Currently one callback is exposed:

// Print a message to the console panel (desktop) or stdout (CLI)
host::log("starting heavy work");

Messages appear in the same stream as the built-in Log node, tagged with the invoking node's id.

Plugin validation

When you run twistedflow plugin build, the built .wasm is validated before installation:

• Required exports (tf_metadata, tf_execute) must exist
• Node metadata must parse as valid JSON
• Pin data_type values must be from the valid set

Invalid plugins fail with a clear error message — you won't silently ship a broken plugin.

Project Structure

TwistedFlow projects are plain folders on disk. No database, git-friendly by default.

Folder layout

twistedflow.toml

Minimal config file. Currently just holds the project name:

name = "My Project"

Environments (.env files)

Standard dotenv format. Each .env file is an environment:

Access env vars in flows via the EnvVar node. Wire the output pin to wherever you need the value.

# .env.dev
API_KEY=dev-key-12345
BASE_URL=http://localhost:3000
DEBUG=true

Flows (.flow.json)

Each flow is a JSON file in the flows/ directory. A flow contains:

• nodes — array of node objects (type, position, config, pins)
• edges — array of connections between pins
• variables — array of typed variable declarations ({ name, type, default }). Defaults are pre-seeded at execution start.
• viewport — saved zoom/pan position

Flows are created and edited in the desktop app. You can also export/import them as .flow.json files.

Git workflow

Since projects are just files, they work naturally with git:

cd my-project
git init
git add .
git commit -m "initial flow"

# Collaborate
git push origin main