Quick Start

This guide walks you through installing Radhflow, creating a three-node pipeline, and running it. You will read a CSV, filter rows with SQL, and write the results as JSON.

1. Prerequisites

• Node.js 20+ — check with node --version
• Docker (optional) — needed for sandboxed CLI nodes, not required for basic pipelines

2. Install

npm install -g radhflow

Or run without installing:

npx radhflow

Verify the installation:

rf --version

radhflow v0.1.0

3. Create a project

rf init my-pipeline
cd my-pipeline

This creates a Git-backed project:

my-pipeline/
  flow.yaml          # pipeline definition
  nodes/             # generated node code
  .rf/               # runtime state (gitignored)
  .gitignore

4. Define the pipeline

Open flow.yaml. Replace its contents with this three-node pipeline that reads leads from a CSV, filters by score, and writes the results as JSON.

flow.yaml

nodes:
  read-leads:
    type: source
    op: file.read_csv
    params:
      path: leads.csv
    outputs:
      leads:
        type: Table
        schema:
          name: { type: string }
          email: { type: string }
          score: { type: number }

  filter-top:
    type: deterministic
    op: sql.query
    params:
      query: "SELECT * FROM leads WHERE score >= 80"
    inputs:
      leads:
        type: Table
        from: ref(read-leads.leads)
    outputs:
      qualified:
        type: Table

  write-output:
    type: deterministic
    op: file.write_json
    params:
      path: qualified-leads.json
    inputs:
      qualified:
        type: Table
        from: ref(filter-top.qualified)

5. Add test data

Create a leads.csv file in the project root:

leads.csv

name,email,score
Alice,alice@example.com,92
Bob,bob@example.com,45
Carol,carol@example.com,88
Dave,dave@example.com,71
Eve,eve@example.com,95

6. Run the pipeline

rf run

Expected output:

[read-leads]   ✔ Read 5 rows from leads.csv
[filter-top]   ✔ 3 rows matched (score >= 80)
[write-output] ✔ Wrote qualified-leads.json

Pipeline completed. 3 nodes executed in 0.4s.

7. Check the results

cat qualified-leads.json

[
  { "name": "Alice", "email": "alice@example.com", "score": 92 },
  { "name": "Carol", "email": "carol@example.com", "score": 88 },
  { "name": "Eve", "email": "eve@example.com", "score": 95 }
]

8. Inspect the pipeline

Use rf inspect to see the graph structure and execution status:

rf inspect

Pipeline: my-pipeline (3 nodes, 2 edges)

  read-leads [source]
    └─ leads (Table: 5 rows) ──> filter-top.leads

  filter-top [deterministic]
    └─ qualified (Table: 3 rows) ──> write-output.qualified

  write-output [deterministic]
    └─ qualified-leads.json (written)

Last run: 0.4s, all nodes succeeded.

What just happened

1. read-leads read the CSV and produced a typed Table with 5 rows.
2. filter-top ran a DuckDB SQL query against that Table, selecting rows with score >= 80.
3. write-output wrote the 3 matching rows as JSON.

No LLM ran. No tokens burned. Same input produces identical output every time.

Next steps

• Key Concepts — understand pipelines, nodes, ports, edges, and data types
• Pipeline YAML — full reference for flow.yaml syntax
• Data Operations — filter, map, sort, join, group, and more
• Troubleshooting — common issues and how to fix them