Quickstart

Get up and running with Kuetix Engine in just a few minutes. This guide will walk you through installation, configuration, and running your first workflow.

Prerequisites

Before you begin, ensure you have the following installed:

Go 1.21+ - Download Go
Make (optional) - For convenience build commands
Docker (optional) - For containerized deployments

Installation

Step 1: Add Engine as Go Module

First, create a new Go project and add the Kuetix Engine as a dependency:

# Create a new project directory
mkdir myapp
cd myapp

# Initialize Go module
go mod init myapp

# Add Kuetix Engine as dependency
go get github.com/kuetix/engine@latest

Step 2: Install kue CLI Tool

The kue CLI lives in its own repository at github.com/kuetix/kue. It consumes the engine as a Go module dependency.

Option A: Using Makefile (Recommended)

git clone https://github.com/kuetix/kue.git
cd kue
make install

Option B: Using install.sh

git clone https://github.com/kuetix/kue.git
cd kue
make build
./install.sh kue

Verify installation:

kue version

Initial Setup

Step 3: Initialize Your Project with kue

Use kue create to generate your project structure. Choose from different application types:

# Initialize a CLI application
kue create --name myapp --app-type cli
cd myapp

# Or initialize other types:
# kue create --name myapp --app-type api        # Web API
# kue create --name myapp --app-type consumer   # AMQP Consumer
# kue create --name myapp --app-type service    # Background Service

The kue create command generates:

Complete project structure
Makefile with build targets
runner.sh script for development tasks
Example workflows and modules
Docker configuration

Step 4: Generate Components

Use kue add to create workflows, features, solutions, or module methods:

# Generate a workflow
kue add workflow PaymentProcess

# Generate a feature
kue add feature UserManagement

# Generate a solution
kue add solution ECommerce

# Generate a module
kue add module payment

Step 5: Generate Module Cache

Before building, generate the module metadata cache:

kue update --verbose

This creates:

modules/di.go - Dependency injection configuration
modules/meta.go - Module metadata
modules.json - Module registry

Step 6: Build Your Application

Build your application using Go:

# Using Makefile (recommended)
make build-cli

# Or using go build directly
go build -o runtime/bin/myapp-cli ./cmd/cli

Step 7: Run Your Application

Execute workflows with your built application:

./runtime/bin/myapp-cli workflows/common/example.wsl

Configure Environment Variables (Optional)

:::tip Configuration is Optional The engine works with zero configuration using sensible defaults. You only need to create a .env file if you want to customize settings. :::

If you want to customize environment settings, copy the example file:

cp .env.example .env

Edit .env to configure your application settings:

NAME=kuetix
APP_ENV=development
CONFIG_PATH=etc/development

Default values if no .env file exists:

APP_ENV: production
CONFIG_PATH: etc/production

Your First Workflow

Option 1: Standard WSL

Create a new WSL file at runtime/workflows/my_hello/hello.wsl:

module my_hello

import services/common

const {
    event: "hello",
    description: "My first workflow",
    version: "1.0.0"
}

workflow hello {
    start: Greet

    state Greet {
        action converse/speak.Say(on: message, v: {response: "Hello, World!", statusCode: 200}) as Response
        on success -> Finish(Response)
    }

    state Finish(Response) {
        action services/common/response.ResponseValue(message: $Response.message, statusCode: 200)
        end ok
    }
}

Option 2: SimplifiedWSL (Concise Syntax)

Or use SimplifiedWSL for a more concise version at runtime/workflows/my_hello/hello.swsl:

module my_hello

import services/common

const {
    event: "hello",
    description: "My first workflow",
    version: "1.0.0"
}

// Define error handler
def services/common/response.ResponseValue(message: "error", statusCode: 500) as errorHandler -> .

// Main flow
converse/speak.Say(on: message, v: {response: "Hello, World!", statusCode: 200}) as Response <- errorHandler ->
services/common/response.ResponseValue(message: $Response.message, statusCode: 200) -> .

SimplifiedWSL uses pipeline operators (->) and error binding (<-) for a more compact, readable syntax. See the Simplified WSL Guide for details.

Generate Templates (Optional)

You can also use the kue add command to create workflows, modules, and other components:

# Generate a workflow
kue add workflow MyWorkflow

# Generate a module with transitions
kue add module payment

# Generate a feature
kue add feature PaymentProcessor

# Generate a solution
kue add solution ECommerce

See the CLI Reference for complete kue documentation.

Run the Workflow

First, build your application:

make build-cli

Then execute your workflow:

./runtime/bin/myapp-cli workflows/my_hello/hello.wsl

Additional options:

# Verbose mode
./runtime/bin/myapp-cli -v workflows/my_hello/hello.wsl

# With parameters
./runtime/bin/myapp-cli workflows/my_hello/hello.wsl message="Hello from CLI!"

# Run multiple instances concurrently
./runtime/bin/myapp-cli --amount=5 workflows/my_hello/hello.wsl

Understanding the Workflow Structure

Let's break down the Hello World workflow:

Module Declaration

module my_hello

Declares the namespace for this workflow file.

Imports

import services/common

Imports required modules that provide transition handlers.

Constants

const {
    event: "hello",
    description: "My first workflow",
    version: "1.0.0"
}

Defines metadata and constants accessible as $constants.*.

Workflow Definition

workflow hello {
    start: Greet
    ...
}

Defines a workflow named hello that starts at the Greet state.

States

state Greet {
    action converse/speak.Say(on: message, v: {...}) as Response
    on success -> Finish(Response)
}

Each state:

Executes an action (transition handler)
Uses as to capture the result
Uses on success or on error to define next steps

Terminal States

state Finish(Response) {
    action services/common/response.ResponseValue(...)
    end ok
}

Terminal states use end ok or end error to complete the workflow.

Next Steps

Now that you've run your first workflow, explore these topics:

Getting Started - Learn about architecture and core concepts
WSL Documentation - Master the Workflow Specific Language
Examples - Explore more complex workflow patterns
Configuration - Configure the engine for your needs

Common Commands

The typical workflow follows these steps:

1. Setup

Command	Description
`go mod init <name>`	Initialize Go module
`go get github.com/kuetix/engine@latest`	Add engine dependency
`git clone https://github.com/kuetix/kue && cd kue && make install`	Install kue CLI

2. Project Initialization

Command	Description
`kue create --name <name> --app-type <type>`	Initialize project (cli, api, consumer, service)

3. Component Generation

Command	Description
`kue add workflow <name>`	Generate a workflow
`kue add feature <name>`	Generate a feature
`kue add solution <name>`	Generate a solution
`kue add module <name>`	Generate a module with transitions

4. Build & Run

Command	Description
`kue update --verbose`	Generate module metadata cache
`go build -o runtime/bin/<app>-cli ./cmd/cli`	Build application
`make build-cli`	Build CLI application (via Makefile)
`./runtime/bin/<app>-cli <workflow>`	Run a workflow
`./runtime/bin/<app>-cli -v <workflow>`	Run with verbose logging

5. Testing & Validation

Command	Description
`make test`	Run tests via Makefile

Using Generated Projects

When you create a project with kue create, you get:

Makefile Commands

Generated projects include a Makefile with build and install targets:

# Build commands
make                    # Build CLI application (default)
make build-cli          # Build CLI application
make build-api          # Build API server
make build-consumer     # Build consumer
make build-service      # Build service
make all                # Build all components

# Install commands
make install            # Install all built binaries
make install-cli        # Install CLI binary only
make install-api        # Install API binary only
make install-consumer   # Install consumer binary only
make install-service    # Install service binary only

# Other commands
make test               # Run tests
make clean              # Clean build artifacts

Install locations:

$GOPATH/bin if $GOPATH is set
/usr/local/bin otherwise (may require sudo)

Example workflow:

# Build and install CLI
make build-cli
make install-cli

# Or build and install everything
make all
make install

Runner Script

The runner.sh script provides convenient development commands:

# Run a workflow
./runner.sh run workflows/common/example.wsl

# Test all workflows
./runner.sh test

# Validate all workflows
./runner.sh validate

# Build the application
./runner.sh build

# Clean generated files
./runner.sh clean

Troubleshooting

"Module not found" errors

Ensure you've run kue update --verbose to generate the module cache.

"Workflow not found" errors

Check that your workflow file is in the correct location under runtime/workflows/.

Build errors

Run go mod tidy to ensure all dependencies are properly resolved.

Ready to dive deeper? Check out the Getting Started guide for a comprehensive overview of Kuetix Engine's architecture and concepts.

Prerequisites​

Installation​

Step 1: Add Engine as Go Module​

Step 2: Install kue CLI Tool​

Option A: Using Makefile (Recommended)​

Option B: Using install.sh​

Initial Setup​

Step 3: Initialize Your Project with kue​

Step 4: Generate Components​

Step 5: Generate Module Cache​

Step 6: Build Your Application​

Step 7: Run Your Application​

Configure Environment Variables (Optional)​

Your First Workflow​

Option 1: Standard WSL​

Option 2: SimplifiedWSL (Concise Syntax)​

Generate Templates (Optional)​

Run the Workflow​

Understanding the Workflow Structure​

Module Declaration​

Imports​

Constants​

Workflow Definition​

States​

Terminal States​

Next Steps​

Common Commands​

1. Setup​

2. Project Initialization​

3. Component Generation​

4. Build & Run​

5. Testing & Validation​

Using Generated Projects​

Makefile Commands​

Runner Script​

Troubleshooting​

"Module not found" errors​

"Workflow not found" errors​

Build errors​