Gremlins Flows

A Node.js CLI engine for executing configurable steps defined in JSON files, with support for result interpolation between steps.

Quick Start

# Execute a flow with npx
npx gremlins-flow execute ./data/sample-01.json --log trace

# Show flow information with npx
npx gremlins-flow explain ./data/sample-01.json

Installation

# Install globally
npm install -g gremlins-flow

CLI Usage

# Execute a flow (after npm install)
npx gremlins-flow execute <file> [options]

# Show flow information
npx gremlins-flow explain <file>

# Development (from source)
tsx src/index.ts execute <file> [options]
tsx src/index.ts explain <file>

Execute Command

Runs the steps defined in a JSON file.

npx gremlins-flow execute ./data/sample-01.json
npx gremlins-flow execute ./data/sample-01.json --log debug
npx gremlins-flow execute ./data/sample-01.json --log trace
npx gremlins-flow execute ./data/sample-01.json --delay 5000

Options:

| Option | Description | Default | |--------|-------------|---------| | -l, --log <level> | Log level: trace, debug, info, warn, error, silent | silent | | -d, --delay <ms> | Delay in milliseconds between steps | 1000 |

Explain Command

Displays a table with flow information without executing it.

npx gremlins-flow explain ./data/sample-01.json

Flow File Structure

A flow is defined in JSON with the following structure:

{
  "title": "My Flow",
  "steps": [
    {
      "key": "uniqueStepKey",
      "type": "data" | "http",
      "description": "Optional description",
      // ... step-specific properties
    }
  ]
}

Step Types

data Step

Stores configuration data without performing operations.

{
  "key": "settings",
  "type": "data",
  "data": {
    "propertyOne": "...",
    "propertyTwo": "..."
  }
}

http Step

Executes HTTP requests to remote servers.

{
  "key": "getData",
  "type": "http",
  "http": {
    "method": "GET", // GET|POST|PUT|DELETE|PATCH"
    "url": "https://api.example.com",
    "headers": { 
      "Content-Type": "application/json"
    },
    "body": { // Or null
      "one": "abc", 
      "two": 2, 
      "three": true
    }
    "formData": { // Or null
      "four": "...", 
      "five": "..."
    } 
  }
}

Note: Use body for JSON payloads, formData for multipart/form-data.

Conditions

⚠️ Deprecation Notice: The condition property (single) is deprecated and will be removed in a future version. Please use conditions (plural, array) instead.

The conditions property allows skipping a step based on one or more expressions. All conditions must evaluate to true (AND logic) for the step to execute:

{
  "key": "optionalStep",
  "type": "http",
  "http": { 
    // ... 
  },
  "conditions": [
    "{{previousStep.isExecuted}} == true",
    "{{settings.data.amount}} > 10"
  ]
}

• If conditions is absent or all conditions evaluate to true → step executes normally
• If any condition evaluates to false → step is skipped (isExecuted: false)

Single condition (deprecated):

{
  "key": "optionalStep",
  "type": "http",
  "http": { 
    // ... 
  },
  "condition": "{{previousStep.isExecuted}} == true"
}

Interpolation

Interpolation allows referencing results from previous steps using the {{stepKey.path.to.value}} syntax.

Syntax

{{stepKey.path.to.value}}

Examples

• {{settings.data.tenantId}}
• {{auth.http.statusCode}}
• {{auth.http.body.access_token}}
• {{posts.http.body.items[0].id}}

Rules

1. Execution order: Steps execute sequentially in the order they appear
2. Resolution: Before each step executes, all {{...}} patterns are resolved using previous step results
3. Path resolution: Dot notation accesses nested properties
4. Full result access: {{stepKey}} returns the entire step result object
5. Array access: Use bracket notation: {{stepKey.http.body.items[0].id}}

Interpolation Constants

Constants are dynamically generated values that start with $:

| Constant | Description | Example | |----------|-------------|---------| | $guid | UUID v4 | 3c7b69b6-3177-4440-9564-47e82eee6a0e | | $nguid | UUID without dashes (32 chars) | 3c7b69b631774440956447e82eee6a0e | | $now | Current date/time (ISO 8601) | 2026-04-13T12:28:24.472Z | | $date | Current date (yyyy-MM-dd) | 2026-04-13 | | $env.VAR_NAME | Read an environment variable | {{$env.MY_POST_ID}} → "3" |

Environment variable example:

{
  "key": "getPostByEnvironmentVariable",
  "type": "http",
  "http": {
    "method": "GET",
    "url": "https://api.example.com/posts/{{$env.MY_POST_ID}}"
  }
}

Note: If the environment variable is not defined, an interpolation error is thrown.

Cast Operators

Cast operators preserve or convert the type of an interpolated value:

| Operator | Description | Example | |----------|-------------|---------| | \|int | Convert to integer | {{value\|int}} → 10 | | \|float | Convert to decimal | {{value\|float}} → 19.99 | | \|bool | Convert to boolean | {{value\|bool}} → true | | \|string | Convert to string | {{value\|string}} → "10" |

Step Result Structure

Each step produces a result object:

{
  "key": "stepKey",
  "type": "data" | "http",
  "data" | "http": { ... },
  "isExecuted": true | false
}

Inputs

The inputs property declares input parameters that can be interpolated within the step using $inputs.propertyName:

{
  "key": "updatePost",
  "type": "http",
  "inputs": {
    "postId": "{{fetchPosts.http.body[0].id}}",
    "postTitle": "Updated Title"
  },
  "http": {
    "method": "PUT",
    "url": "https://jsonplaceholder.typicode.com/posts/{{$inputs.postId}}",
    "body": {
      "title": "{{$inputs.postTitle}}"
    }
  }
}

Behavior:

1. inputs are resolved before step execution, using results from previous steps
2. Resolved values are accessible via $inputs.propertyName within the same step
3. The $inputs source is only available within the step that defines it

Error Handling

Interpolation Error

[ERROR] Step "stepKey": interpolation can not be resolved "interpolationString"

HTTP Error

[ERROR] Step "stepKey": HTTP request failed - statusCode statusMessage

Project Structure

X:/gremlins-flow/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── ConfigLoader.ts       # JSON loading and validation
│   ├── ExecutionContext.ts   # Stores step results
│   ├── InterpolationEngine.ts # Interpolation engine
│   ├── FlowEngine.ts         # Orchestrates step execution
│   ├── logger.ts             # Logging system
│   └── handlers/
│       ├── DataHandler.ts     # "data" step handler
│       └── HttpHandler.ts     # "http" step handler
├── data/
│   ├── sample-01.json         # Sample flow file
│   └── sample-02.json         # Other sample file
└── package.json

Dependencies

• typescript - TypeScript compilation
• tsx - Run TypeScript without compilation
• axios - HTTP requests
• commander - CLI argument parsing
• loglevel - Logging
• console-table-printer - Colored table output