flowdsl CLI

flowdsl is the lightweight, standalone toolchain for working with FlowDSL files and IR module YAML. It has no dependency on go-framework, MongoDB, or any transport backend — only uuid and yaml.v3.

Use flowdsl in CI pipelines, editor integrations, or any context where you want IR tooling without the full framework stack.

Installation

go install github.com/redelay/go-flowdsl/cmd/flowdsl@latest

Commands

validate

Parse and validate a FlowDSL YAML file. Runs structural validation via flowdsl.Validate. Prints all diagnostics with [E]/[W]/[I] prefixes and exits with code 1 on errors.

flowdsl validate app.flow.yaml

Output on success:

ok — no issues found

Output on failure:

[E] FDL010: event "order_event" has no entity_type
[W] FDL002: version is empty

gen

Scaffold a Go module directory from an ir.Module YAML file. Validates the module with modval first, then generates Go stubs via modgen.Scaffold. Prints each written file path. Existing files are not overwritten.

flowdsl gen modules/orders.module.yaml -o ./modules/orders/

svg

Generate an SVG visual diagram from an ir.Module YAML file.

flowdsl svg modules/auth.module.yaml -o auth.svg

The diagram shows entities, events, config, CRUD operations, settings, commands, queries, workflows, schedules, consumers, dependencies, and provides. Supports dark mode via prefers-color-scheme.

compile

Compile a FlowDSL or business model YAML file to a fully enriched IR document. Runs the Import + Validate + Resolve + Enrich pipeline and writes the result to stdout. Diagnostics go to stderr. Exit code 1 on errors.

flowdsl compile app.flow.yaml                      # FlowDSL → IR JSON (default)
flowdsl compile app.flow.yaml --out yaml           # FlowDSL → IR YAML
flowdsl compile model.yaml -f businessmodel        # businessmodel → IR JSON

Comparison with redelayctl

redelayctl CLI

redelayctl is the full-featured command-line tool for working with Redelay specifications. It builds on the go-framework core compilation pipeline and adds AsyncAPI and OpenAPI format support, scaffold generation, drift auditing, and format conversion — everything the portable flowdsl CLI provides, plus the framework-specific formats.

Powered by the core compilation pipeline.

Installation

cd go-framework
go install ./cmd/redelayctl/

Commands

validate

Validate a FlowDSL file. Runs both FlowDSL structural validation and full IR validation.

redelayctl validate app.flow.yaml

Output:

OK - no errors

Or on failure:

ERROR [FDL010] flowdsl: event "order_event" has no entity_type
WARN  [VAL003] validator: document version is empty
error: 1 errors found

validate-module

Validate a module YAML file against Redelay naming conventions, reference integrity, and structural rules. Catches errors early — before code generation or deployment.

redelayctl validate-module modules/auth/module.yaml

Output:

OK — auth (v1.0.0): 0 warnings

Or on failure:

ERROR [MV001] module ID is required
ERROR [MV021] config key "jwt_secret" must be UPPER_SNAKE_CASE
WARN  [MV010] module version is empty
error: 2 error(s) found

Validation rules include:

• Required fields (ID, name)
• Semver version format
• Entity IDs must be prefixed with module ID (e.g. auth.token)
• Event names must contain a dot separator
• Config keys must be UPPER_SNAKE_CASE with module prefix
• Settings keys must be lower_snake_case
• CRUD entity refs must match declared entities
• No duplicate entity/event IDs
• No self-dependencies

scaffold

Generate a Go module directory from a module YAML file. Produces working Go boilerplate with factory registration, route stubs, and embedded module YAML — ready for business logic implementation.

redelayctl scaffold auth.module.yaml                    # output to ./auth/
redelayctl scaffold auth.module.yaml ./modules/auth/    # output to custom dir

Generated files:

Existing files are not overwritten by default. Pass --force to regenerate.

audit

Compare two module YAML files (e.g. declared spec vs runtime export) and report structural drift. Useful for CI checks to ensure code stays in sync with module definitions.

redelayctl audit modules/auth/module.yaml runtime-export/auth.yaml

Output:

--- Drift report for "auth" ---
[+] events: auth.mfa_enabled
[-] config: AUTH_OLD_SETTING
[~] entities: auth.token (field count: 3 → 5)
3 difference(s) detected

Drift kinds:

• + added — present in actual, missing from declared
• - removed — present in declared, missing from actual
• ~ changed — present in both but different

import

Import a source format and output the canonical IR as JSON.

redelayctl import openapi api.yaml
redelayctl import asyncapi events.yaml
redelayctl import businessmodel model.yaml

Supported formats: openapi, asyncapi, businessmodel.

OpenAPI files with .json extension are parsed as JSON; .yaml/.yml as YAML.

export

Export an IR document (JSON or YAML) to a target format.

redelayctl export json app.ir.yaml       # IR → JSON
redelayctl export yaml app.ir.json       # IR → YAML
redelayctl export flowdsl app.ir.json    # IR → FlowDSL YAML
redelayctl export openapi app.ir.json    # IR → OpenAPI tool schema JSON

Supported target formats: json, yaml, flowdsl, openapi.

convert

Convert directly between formats (import → export in one step).

redelayctl convert flowdsl json app.flow.yaml
redelayctl convert openapi flowdsl api.yaml
redelayctl convert asyncapi openapi events.yaml
redelayctl convert businessmodel yaml model.yaml

Source formats: flowdsl, openapi, asyncapi, businessmodel. Target formats: json, yaml, flowdsl, openapi.

generate

Export an IR document's modules as individual YAML files — one file per module.

redelayctl generate app.ir.json                # writes to current directory
redelayctl generate app.ir.yaml ./modules/     # writes to ./modules/

Each module becomes a <name>.module.yaml file. This is useful for generating module files from a compiled IR document.

diagram

Generate an SVG visual diagram from a module YAML file.

redelayctl diagram auth.module.yaml                  # output to stdout
redelayctl diagram auth.module.yaml auth-diagram.svg  # output to file

The diagram shows the module at the center with surrounding cards for each section: entities, events, config, CRUD operations, settings, commands, queries, workflows, schedules, consumers, dependencies, and provides. Supports dark mode via prefers-color-scheme CSS media query.

ir

Parse a FlowDSL file and output the canonical IR as JSON. Shorthand for import flowdsl.

redelayctl ir app.flow.yaml

version

redelayctl version
# redelayctl 0.1.0

Format conversion matrix

All conversions go through the canonical IR, so any format can be converted to any other format.

Examples

Validate and inspect a FlowDSL app

# Check for errors
redelayctl validate myapp.flow.yaml

# View the canonical IR
redelayctl ir myapp.flow.yaml | jq .

# See module names
redelayctl ir myapp.flow.yaml | jq '[.modules[].name]'

Convert an OpenAPI spec to FlowDSL

redelayctl convert openapi flowdsl petstore.yaml > petstore.flow.yaml

Generate tool schemas from an AsyncAPI spec

redelayctl convert asyncapi openapi events.yaml > tools.json

Generate module files from an IR document

# Export individual YAML files
redelayctl generate myapp.ir.yaml ./modules/

# Generate diagrams for all modules
for f in ./modules/*.module.yaml; do
  redelayctl diagram "$f" "${f%.module.yaml}.svg"
done

Full module development workflow

# 1. Write module.yaml (or generate from IR)
redelayctl generate myapp.ir.yaml ./modules/

# 2. Validate the definition
redelayctl validate-module ./modules/orders.module.yaml

# 3. Scaffold Go boilerplate
redelayctl scaffold ./modules/orders.module.yaml ./modules/orders/

# 4. Implement business logic in the generated stubs

# 5. Generate visual diagram
redelayctl diagram ./modules/orders.module.yaml orders.svg

# 6. Audit for drift (CI)
redelayctl audit ./modules/orders.module.yaml runtime-export/orders.yaml