The nf CLI

npx --yes @node-flow-dev/cli@1.0.0 help

git clone https://github.com/dsardar099/node-flow.git
cd node-flow && pnpm install
pnpm nf help

export NF_URL=https://flows.example.com
export NF_API_KEY=nf_...
export NF_NAMESPACE=default

DATABASE_URL=postgres://nodeflow:pw@localhost:5433/nodeflow nf migrate

Applied migrations:
  0036-ai
  0037-trace-context

nf migrate --json
# { "applied": ["0036-ai", "0037-trace-context"] }

nf bootstrap --namespace default

Created namespace "default" (0193c0f1-…)
Applied migrations: 0001-core-schema, …

API key:
  nf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This is shown once and cannot be recovered. Store it now.

Try it:
  curl -H "X-API-Key: nf_xxxx…" http://localhost:3000/v1/auth/whoami

# A narrowly-scoped key for a CI pipeline
nf bootstrap --namespace acme --key-name ci --scopes executions:read,executions:start --json

{
  "namespaceId": "0193c0f1-…",
  "namespaceCreated": true,
  "migrationsApplied": [],
  "apiKeyId": "0193c0f2-…",
  "token": "nf_…"
}

nf create-user --namespace default \
  --email ada@example.com --name Ada \
  --password 'a-password-that-meets-the-policy'

nf workflows list

NAME             VERSION  TAGS           DESCRIPTION
checkout         v3       team:payments  Charge, then ship.
fulfil_order     v1       -
rag_answer       v2       ai:enabled     Answers from the handbook.

nf workflows list --json | jq '.[] | select(.tags | index("team:payments"))'

nf workflows get checkout
nf workflows get checkout --version 2

nf workflows get checkout > checkout.json
nf workflows get checkout | jq '.tasks[].taskReferenceName'

nf workflows register checkout.json
nf workflows register ./workflows/          # every *.json in the directory, sorted
nf workflows register a.json b.json c.json

registered checkout v3  (checkout.json)
registered refund v1    (refund.json)

nf workflows register ./workflows/ --json
# { "file": "workflows/checkout.json", "name": "checkout", "version": 3 }

# Fire and forget — prints the id
nf run checkout --input '{"orderId":"A-1","amount":99}'
# started checkout: 0193c0f1-…

# Input from a file
nf run checkout --input @order.json

# Wait for the result
nf run checkout --input '{"orderId":"A-1"}' --wait 60

0193c0f1-…  COMPLETED
{
  "receipt": "txn_abc"
}

if nf run nightly_reconcile --wait 60; then
  echo "reconciled"
else
  case $? in
    1) echo "failed — check the run" ;;
    2) echo "still running, not waiting" ;;
  esac
fi

nf executions list
nf executions list --workflow checkout --status FAILED --limit 50

ID                                    WORKFLOW      STATUS     STARTED
0193c0f1-…                            checkout v3   FAILED     2026-09-19T14:22:03.112Z
0193c0e8-…                            checkout v3   COMPLETED  2026-09-19T14:19:44.001Z

nf executions get 0193c0f1-…

checkout  FAILED
reason: task "ship" ended as FAILED after 4 attempt(s)
TASK       TYPE     STATUS     ATTEMPT
charge     SIMPLE   COMPLETED  1
ship       SIMPLE   FAILED     4

nf executions get 0193c0f1-… --json | jq '.tasks[] | select(.status=="FAILED")'

nf executions cancel-task 0193c0f1-… transcribe

cancelled transcribe; workflow is PAUSED
the worker was not stopped — its result will be refused when it reports

nf executions rerun-tasks 0193c0f1-… transcribe

re-running transcribe

stale — still holding output from the run being replaced:
  transcreate, speech_generate
re-run with --cascade to replace these too

nf executions rerun-tasks 0193c0f1-… transcribe --cascade

nf executions rerun-tasks 0193c0f1-… transcribe --json | jq .staleDownstream

nf tail 0193c0f1-…

14:22:03  charge                   SCHEDULED
14:22:03  charge                   IN_PROGRESS
14:22:04  charge                   COMPLETED
14:22:04  ship                     SCHEDULED
14:22:06  ship                     FAILED (attempt 1) — connection refused
14:22:08  ship                     SCHEDULED (attempt 2)
── workflow RUNNING

# Start and follow in one line
ID=$(nf run checkout --input '{"orderId":"A-1"}' --json | jq -r .workflowId)
nf tail "$ID"

nf replay 0193c0f1-…
# v3 reproduces the run exactly

nf replay 0193c0f1-… --version 4
# 2 difference(s) against v4:
#   - task "ship" was scheduled with a different input
#   - workflow output key "receipt" resolved to null

nf export --out bundle.json                       # everything
nf export --workflows checkout,refund --out b.json
nf export | jq .                                  # to stdout

nf import bundle.json --dry-run
nf import bundle.json

# Promote from staging to production
NF_URL=https://staging.example.com NF_API_KEY=$STAGING nf export --workflows checkout --out checkout.json
NF_URL=https://prod.example.com    NF_API_KEY=$PROD    nf import checkout.json --dry-run
NF_URL=https://prod.example.com    NF_API_KEY=$PROD    nf import checkout.json --workflow-conflicts new-version

nf test greet.test.json
nf test ./tests/                      # every *.json in the directory
nf test a.json b.json

✓ tests/happy-path.json   COMPLETED  7 ms
✗ tests/saga.json         FAILED     11 ms
    task cancel_hotel is never run, expected COMPLETED

1 passed, 1 failed

{
  "definition": {
    "name": "book_trip",
    "version": 1,
    "inputParameters": ["city"],
    "tasks": [
      {
        "name": "book_hotel",
        "taskReferenceName": "book_hotel",
        "type": "SIMPLE",
        "inputParameters": { "city": "${workflow.input.city}" },
        "compensateWith": {
          "name": "cancel_hotel",
          "taskReferenceName": "cancel_hotel",
          "type": "SIMPLE",
          "inputParameters": { "bookingId": "${book_hotel.output.bookingId}" }
        }
      },
      {
        "name": "book_flight",
        "taskReferenceName": "book_flight",
        "type": "SIMPLE",
        "inputParameters": { "city": "${workflow.input.city}" }
      }
    ]
  },

  "input": { "city": "lisbon" },

  "taskDefs": {
    "book_flight": { "retryCount": 0 }
  },

  "mocks": {
    "book_hotel": { "output": { "bookingId": "b-1" } },
    "book_flight": { "status": "FAILED_WITH_TERMINAL_ERROR", "reason": "no seats" },
    "cancel_hotel": { "output": { "cancelled": true } }
  },

  "expect": {
    "status": "FAILED",
    "tasks": { "cancel_hotel": "COMPLETED" }
  }
}

nf test --definition checkout.json \
        --input '{"orderId":"A-1"}' \
        --mocks '{"charge":{"output":{"txnId":"t1"}}}'

✓ tests/partial.json  COMPLETED  4 ms
    note: completed with empty output because nothing mocked ship, notify

const result = await simulate(definition, { input, mocks });
expect(result.unmocked).toEqual([]);

nf test ./tests/ --json

{"file":"tests/saga.json","passed":false,"status":"FAILED","output":{},"problems":["task cancel_hotel is never run, expected COMPLETED"],"unmocked":[]}

name: workflows
on: [pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with: { node-version: 24 }

      # No server, no database, no containers.
      - run: npx --yes @node-flow-dev/cli@1.0.0 test ./workflows/tests/

  deploy:
    needs: validate
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    env:
      NF_URL: ${{ secrets.NF_URL }}
      NF_API_KEY: ${{ secrets.NF_API_KEY }}
      NF_NAMESPACE: production
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-node@v5
        with: { node-version: 24 }
      - run: npx --yes @node-flow-dev/cli@1.0.0 workflows register ./workflows/