CLI Reference

Kuetix Engine provides a comprehensive command-line tool:

kue - Comprehensive CLI for project scaffolding, code generation, and workflow execution

Installation

The Kuetix Engine is used as a Go module dependency. The kue CLI lives in its own repository at github.com/kuetix/kue and consumes the engine as a dependency.

Step 1: Add Engine as Go Module

# Create your project
mkdir myapp && cd myapp

# Initialize Go module
go mod init myapp

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

Step 2: Install kue CLI Tool

Using Makefile (Recommended)

# Clone the kue repository
git clone https://github.com/kuetix/kue
cd kue

# Install using Makefile (builds and installs)
make install

# Verify
kue version

Using install.sh

# Clone the kue repository
git clone https://github.com/kuetix/kue
cd kue

# Build the binary, then run installer
make build
./install.sh kue

# Verify
kue version

The kue binary will be installed to (in priority order):

$GOBIN if set
$GOPATH/bin if $GOPATH is set
$HOME/go/bin
/usr/local/bin (may require sudo)

kue

The kue CLI is a comprehensive tool for creating, managing, and building Kuetix workflow applications. Its source lives in github.com/kuetix/kue at cmd/cli/main.go (the resulting binary is named kue).

Typical Workflow

Add engine as module: go get github.com/kuetix/engine@latest
Install kue: Via Makefile, install.sh, or go install
Create project: kue create --name myapp --app-type cli
Add components: kue add <type> <name> where type is workflow, feature, solution, module, transition, or package
Update cache: kue update
Build & run: kue run or make build-cli && ./runtime/bin/myapp-cli workflows/example.wsl
Publish package: kue login then kue package publish

Commands

kue create - Create a new application/project from template
kue add - Add modules, workflows, features, solutions, transitions, and packages
kue run - Build and run a project (compile check for packages)
kue package - Manage Kuetix package dependencies
kue register - Register a new Kuetix account
kue login - Authenticate with Kuetix API
kue logout - Remove stored authentication data
kue profile - Manage authenticated user profile (get, update)
kue update - Update module cache (di.go, meta.go, modules.json)
kue show - Show list of applications, solutions, features, and workflows
kue templates - Manage template cache (download, update, clear, status)
kue version - Show version information

kue create

Create a new Kuetix application or package with complete project scaffolding.

Usage:

kue create --name <project-name> [options]

Options:

--name, -n - Project name (required)
--app-type, -a - Application type (default: cli)
- cli - CLI application
- api - Web API application
- consumer - AMQP queue consumer (Apache ActiveMQ)
- service - Background service/daemon
- package - Reusable package with workflows/features/solutions
- all - Full application with all types
--output, -o - Output directory (default: current directory)
--force, -f - Overwrite existing directory without confirmation
--help, -h - Show help message

Examples:

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

# Create an API server
kue create -n myapi -a api

# Create a reusable package
kue create -n mypackage -a package

# Create a full application with all types
kue create --name myservice --app-type all

# Create in a specific directory
kue create --name myapp --app-type cli --output ./projects

What Gets Generated:

Project directory structure
Go module configuration (go.mod)
Application entry points (cmd/cli, cmd/api, etc.)
Example workflows, features, and solutions
Example transition module
Makefile with build targets
runner.sh script for development tasks
Dockerfile and docker-compose.yml
README.md with project documentation
.gitignore with sensible defaults

kue add

Add various components to your Kuetix application.

Subcommands:

kue add module <name> - Add a module with transitions
kue add workflow <name> - Add a workflow
kue add feature <name> - Add a feature
kue add solution <name> - Add a solution
kue add transition [<path>/]<TransitionName> - Add a transition to a module (creates the module if it does not exist)
kue add package - Scaffold a kuetix.json package manifest file

kue add module

Add a new module with transition methods.

Usage:

kue add module <name> [options]

Options:

--output, -o - Output directory (default: current directory)
--help, -h - Show help message

Examples:

# Add a payment module
kue add module payment

# Add with hyphenated name
kue add module user-management

# Add in a specific directory
kue add module order --output ./my-project

Generated Structure:

modules/services/payment/transitions/payment.go

kue add workflow

Add a new workflow definition.

Usage:

kue add workflow <name> [options]

Options:

--output, -o - Output directory (default: current directory)

Examples:

# Add a payment workflow
kue add workflow payment

# Add with hyphenated name
kue add workflow order-processing

Generated Structure:

workflows/common/{name}.wsl

kue add feature

Add a new feature definition that orchestrates workflows.

Usage:

kue add feature <name> [options]

Examples:

# Add a user management feature
kue add feature user-management

# Add a payment gateway feature
kue add feature payment-gateway

Generated Structure:

workflows/features/{name}.wsl

kue add solution

Add a new solution definition for high-level orchestration.

Usage:

kue add solution <name> [options]

Examples:

# Add an e-commerce solution
kue add solution e-commerce

# Add an order system solution
kue add solution order-system

Generated Structure:

workflows/solutions/{name}.wsl

kue add transition

Add a new transition method to a module. The module path and transition name are encoded in a single argument: everything before the last / is the module path and the last segment is the transition name (e.g., in system/billing/payment/ProcessPayment, system/billing/payment is the module path and ProcessPayment is the transition name). If no module path is given, the common module is used. If the target module does not exist, it is created automatically before the transition is appended.

Usage:

kue add transition [<path>/]<TransitionName> [options]
kue add transition <TransitionName> --module <module> [options]

Options:

--module, -m - Module name / path (default: common)
--description, -d - Description comment for the generated transition method
--output, -o - Output directory (default: current directory)
--help, -h - Show help message

Examples:

# Add a transition to a simple module
kue add transition payment/ProcessPayment

# Add a transition with a description
kue add transition payment/ProcessPayment -d 'processes a payment'

# Add a transition using a deep (nested) module path
kue add transition system/billing/payment/ProcessPayment -d 'processes a payment'

# Add a transition with no module path (uses 'common' module)
kue add transition ProcessPayment

# Add a transition using the explicit module flag
kue add transition ValidateUser --module user

# Add a transition with a description and custom output directory
kue add transition notification/SendEmail -d 'sends an email notification' --output ./my-project

Generated / modified file:

modules/services/<module-path>/transitions/<module>.go

Behaviour:

The last path segment of the argument is the transition name; everything before the last / is the module path (which may itself contain multiple segments for nested directories, e.g. system/billing/payment).
Go identifiers (struct name, constructor, etc.) are always derived from the last segment of the module path — e.g. payment from system/billing/payment, not from the transition name ProcessPayment.
If the module file already exists, the new transition method is appended to it.
If the module file does not exist, a new module is created first and then the transition is appended.
The optional --description/-d flag adds a comment to the generated method.

kue add package

Scaffold a kuetix.json package manifest file in the current or specified directory.

Usage:

kue add package [options]

Options:

--output, -o - Output directory (default: current directory)
--help, -h - Show help message

Examples:

# Scaffold kuetix.json in the current directory
kue add package

# Scaffold in a specific directory
kue add package --output ./my-package

Generated File:

kuetix.json

kue run

Build and run a Kuetix Engine project. For package type projects, it performs a compile check (go build ./...). For application types (cli, api, consumer, service), it builds the binary and runs it.

Usage:

kue run [options]

Options:

--name, -n - Project name (used as binary name)
--app-type, -a - Application type: cli, api, consumer, service, package (default: read from application.json)
--output, -o - Project directory (default: current directory)
--help, -h - Show help message

Examples:

# Run project in current directory
kue run

# Compile check a package
kue run -a package

# Build and run API app
kue run -n myapp -a api -o .

# Compile check package at specific path
kue run -n mypackage -a package -o mypackage

kue register

Usage:

kue register [options]

Options:

--host, -h - API host (default: api.kuetix.com)
--email, -e - Email for registration (required)
--password, -p - Password for registration (required)
--name, -n - Display name (optional)
--username, -u - Username (optional)
--help - Show help message

Environment Variables:

KUE_HOST - Default API host

Examples:

# Register a new account
kue register --email user@example.com --password mypassword

# Register with display name
kue register -e user@example.com -p mypassword --name "John Doe" --username johndoe

Authenticate with the Kuetix API and store the login payload locally. Credentials can be provided via flags, stdin, or interactive keyboard input.

Usage:

kue login [options]

Options:

--host, -h - API host (default: api.kuetix.com)
--config, -c - Path to config file (default: ~/.kue/config.json)
--username, -u - Username for login
--password, -p - Password for login
--help - Show help message

Environment Variables:

KUE_HOST - Default API host
KUE_CONFIG_PATH - Default config file path

Credential Input Methods:

Flags: --username and --password
Stdin: pipe username:password or username\npassword
Interactive: if password is missing, prompts securely from keyboard

Examples:

# Login with flags
kue login --username myuser --password mypass

# Login with interactive password prompt
kue login -u myuser

# Login via stdin
echo "myuser:mypass" | kue login

# Login to a custom host
kue login -h localhost:8080 -u admin -p secret

# Use a custom config path
kue login --config /path/to/config.json -u myuser -p mypass

Config File:

{
  "host": "https://api.kuetix.com",
  "secure": true,
  "login": {
    "token": "eyJhbGciOiJIUzI1NiIs..."
  }
}

kue logout

Remove stored Kuetix authentication data from the local config file.

Usage:

kue logout [options]

Options:

--config, -c - Path to config file
--help - Show help message

Examples:

# Logout (removes login data from ~/.kue/config.json)
kue logout

kue profile

Manage the authenticated user profile. Requires prior authentication via kue login.

Usage:

kue profile <subcommand> [options]

Subcommands:

get - Retrieve the authenticated user's profile
update - Update profile fields

kue profile get

Usage:

kue profile get [options]

Options:

--host, -h - API host (default: from config or api.kuetix.com)
--config, -c - Path to config file
--help - Show help message

Examples:

# Get current profile
kue profile get

kue profile update

Usage:

kue profile update [options]

Options:

--host, -h - API host
--config, -c - Path to config file
--name - Display name
--username - Username
--help - Show help message

At least one of --name or --username is required.

Examples:

# Update display name
kue profile update --name "New Name"

# Update username
kue profile update --username newuser

# Update both
kue profile update --name "New Name" --username newuser

kue package

Manage Kuetix package dependencies, including publishing to and fetching from the Kuetix package registry.

Usage:

kue package <subcommand> [options]

Subcommands:

add - Add package from kuetix.json to the registry (requires login)
update - Update package on the registry (requires login)
list - List packages from the registry (requires login)
search - Search remote packages (requires login)
install - Install remote package metadata (requires login)
enable - Enable a module in the current project (generate bootstrap file)
list-local - List modules already enabled in the current project
publish - Update package metadata and print release instructions
show - Show current package information from kuetix.json

kue package add

Usage:

kue package add [options]

Options:

--path, -p - Path to kuetix.json or package directory (default: current directory)
--host, -H - API host
--config, -c - Path to config file
--help - Show help message

kue package update

Update an existing package on the registry.

Usage:

kue package update [options]

Options: Same as kue package add.

kue package publish

Update kuetix.json metadata and print git tag instructions for release.

Usage:

kue package publish [<package>] [options]

Options:

--description, -d - Package description
--version, -v - Package version (e.g., 0.2.0)
--publisher, -p - Publisher name or organisation
--keywords, -k - Comma-separated list of keywords
--output, -o - Package directory (default: current directory)
--help, -h - Show help message

Examples:

# Publish with metadata
kue package publish mypackage -d "billing package" -v 0.2.0 -p acme

# Publish with keywords
kue package publish mypackage -k "billing,payments,orders"

# Publish from current directory
kue package publish

kue package show

Display package information from kuetix.json.

Usage:

kue package show [<path>] [options]

Options:

--path, -p - Path to kuetix.json or package directory
--help, -h - Show help message

Examples:

# Show package info in current directory
kue package show

# Show package info from specific path
kue package show ./my-package

kue package enable

Enable a module in the current project by generating a bootstrap file.

Usage:

kue package enable <module-name> [options]

kue package list

List packages from the remote Kuetix registry.

Usage:

kue package list [options]

kue package list-local

List modules already enabled in the current project.

Usage:

kue package list-local [options]

kue templates

Manage the .kue/templates cache used for project scaffolding.

Usage:

kue templates <subcommand>

Subcommands:

download - Download templates to the local cache
update - Update the cached templates to the latest version
clear - Remove the cached templates
status - Show the current template cache status

Examples:

# Download templates
kue templates download

# Update to latest
kue templates update

# Clear cache
kue templates clear

# Check status
kue templates status

Global Template Options:

These options can be used with any command that uses templates:

Option	Description	Default
`--template-url <url>`	URL to fetch templates from	`https://templates.kuetix.com/latest/`
`--template-version <ver>`	Template version	`latest`
`--template-path <path>`	Local directory path for templates	-
`--template-git <url>`	Git repository URL for templates	-

Template Priority: local path > git > web URL

Environment Variables:

Variable	Description
`KUE_TEMPLATE_URL`	Set default template URL
`KUE_TEMPLATE_VERSION`	Set default template version
`KUE_TEMPLATE_PATH`	Set default template path
`KUE_TEMPLATE_GIT`	Set default template git repository

kue update

Generate module metadata cache for dependency injection.

Usage:

kue update [options]

Options:

--verbose, -v - Verbose mode
--quiet, -q - Quiet mode

Examples:

# Update module cache
kue update

# Update with verbose output
kue update --verbose

What It Does:

The kue update command scans your modules/ directory and generates:

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

Note: Generated cache files are excluded from version control (added to .gitignore).

kue show

Show project components.

Usage:

kue show

Examples:

# Show all project components
kue show

What It Shows:

Applications with type and version
Workflows in workflows/common/
Features in workflows/features/
Solutions in workflows/solutions/
Modules from modules.json

Running Your Application

After building your application with make build-cli or similar, run workflows using the built binary. Workflows are executed via the compiled binary (there is no kue run command).

Usage:

./runtime/bin/<app-name>-cli [options] <workflow> [key1=value1 ...]

Options:

-v - Verbose mode (detailed output)
-q - Quiet mode (minimal output)
--amount=N - Concurrency amount (default: 1)
--retry=N - Retry times on failure (default: 1)
--retry-delay=N - Delay seconds between retries (default: 1)
--restart-policy=<policy> - Restart policy: always, on-failure, stop (default: stop)

Examples:

# Build the application first
make build-cli

# Run a workflow
./runtime/bin/myapp-cli workflows/example.wsl

# Run with verbose output
./runtime/bin/myapp-cli -v workflows/example.wsl

# Run with parameters
./runtime/bin/myapp-cli workflows/example.wsl key1=value1 key2=value2

# Run with concurrency
./runtime/bin/myapp-cli -v --amount=5 workflows/example.wsl

# Run with retry policy
./runtime/bin/myapp-cli --retry=3 --retry-delay=2 workflows/example.wsl

kue version

Show version information.

Usage:

kue version

Generated Project Structure

When you run kue create, the following structure is created:

myproject/
├── cmd/                          # Application entry points
│   ├── cli/main.go              # CLI application
│   ├── api/main.go              # API server
│   ├── consumer/main.go         # AMQP consumer
│   └── service/main.go          # Background service
├── modules/                      # Custom modules
│   └── services/
│       └── example/
│           └── transitions/
│               └── example.go   # Example transition module
├── workflows/                    # Workflow definitions
│   ├── common/                  # Common workflows
│   │   └── example.wsl
│   ├── features/                # Feature workflows
│   │   └── example_feature.wsl
│   └── solutions/               # Solution workflows
│       └── example_solution.wsl
├── runtime/                      # Runtime files
│   ├── etc/                     # Configuration
│   │   ├── development/
│   │   └── production/
│   ├── bin/                     # Build output
│   └── log/                     # Logs
├── tests/                        # Test files
├── docker/                       # Docker configuration
├── .gitignore                    # Git ignore rules
├── Dockerfile                    # Docker image definition
├── docker-compose.yml            # Docker Compose configuration
├── go.mod                        # Go module definition
├── Makefile                      # Build automation
├── README.md                     # Project documentation
└── runner.sh                     # Development runner script

Makefile

Generated projects include a Makefile with these targets:

Targets:

make all - Build CLI application (default)
make build-cli - Build CLI application
make build-api - Build API server
make build-consumer - Build AMQP consumer
make build-service - Build background service
make test - Run tests
make clean - Clean build artifacts
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

Usage:

# Build CLI application (default)
make
# or
make build-cli

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

# Build specific component
make build-api

# Install all components
make all
make install

# Run tests
make test

# Clean build artifacts
make clean

Install Locations:

If $GOPATH is set: $GOPATH/bin/
Otherwise: /usr/local/bin/ (may require sudo)

Build Output: Binaries are created in runtime/bin/:

{project-name}-cli
{project-name}-api
{project-name}-consumer
{project-name}-service

Build Variables:

APP_NAME - Project name
BUILD_DIR - Output directory (runtime/bin)
VERSION - Git version tag
BUILD_TIME - Build timestamp
LDFLAGS - Linker flags with version info
INSTALL_DIR - Installation directory (defaults to $GOPATH/bin or /usr/local/bin)

runner.sh Script

Every generated project includes a runner.sh script for common development tasks.

Usage:

./runner.sh <command> [options]

Commands:

run <workflow> - Run a workflow with automatic cache generation
test - Test all workflows in the project
validate - Validate all workflow files
build - Build the application using Makefile
clean - Clean generated files and artifacts
help - Show help message

Examples:

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

# Test all workflows
./runner.sh test

# Validate all workflow files
./runner.sh validate

# Build the application
./runner.sh build

# Clean generated files
./runner.sh clean

Features:

Automatically generates module cache before running workflows
Colored output for better readability
Error handling with proper exit codes
Test summary with pass/fail counts
Validates workflows recursively

Environment Variables

Key environment variables that affect CLI behavior:

Variable	Description	Default
`NAME`	Application name	`kuetix`
`APP_ENV`	Environment (development/production)	`development`
`CONFIG_PATH`	Path to configuration directory	`runtime/etc`
`KUE_HOST`	Default API host for auth commands	`api.kuetix.com`
`KUE_CONFIG_PATH`	Path to kue config file	`~/.kue/config.json`
`KUE_TEMPLATE_URL`	Default template URL	`https://templates.kuetix.com/latest/`
`KUE_TEMPLATE_VERSION`	Default template version	`latest`
`KUE_TEMPLATE_PATH`	Local directory path for templates	-
`KUE_TEMPLATE_GIT`	Git repository URL for templates	-

Build Commands

Using Generated Project Makefile

In projects created with kue create:

# Build CLI application (default)
make
# or
make build-cli

# Build API server
make build-api

# Build consumer
make build-consumer

# Build service
make build-service

# Run tests
make test

# Clean build artifacts
make clean

Building the Engine from Source

When building the engine itself:

# Clone and enter the engine repo
git clone https://github.com/kuetix/engine
cd engine

# Build the MCP server binary
make build

# Run tests
make test

The engine repository ships the mcp-server binary; the user-facing CLI lives in the kue repository.

Common Workflows

Quick Start with kue

Complete workflow from setup to running your application:

# 1. Create project and add engine as module
mkdir myproject && cd myproject
go mod init myproject
go get github.com/kuetix/engine@latest

# 2. Install kue CLI (separate repository)
git clone https://github.com/kuetix/kue
cd kue && make install
cd ..

# 3. Create project
kue create --name myproject --app-type cli
cd myproject

# 4. Add components
kue add workflow PaymentProcessing
kue add module payment

# 5. Update cache
kue update

# 6. Build application
go build -o runtime/bin/myproject-cli ./cmd/cli
# Or use Makefile
make build-cli

# 7. Run workflow
./runtime/bin/myproject-cli workflows/common/example.wsl

Development Setup (Engine Source)

For contributing to the engine itself:

# 1. Clone the engine repository
git clone https://github.com/kuetix/engine.git
cd engine

# 2. Install kue for development
make install

# 3. Copy environment file (optional)
cp .env.example .env

# 4. Build the engine
make build

# 5. For testing, create a test project
cd /tmp
mkdir testproject && cd testproject
go mod init testproject
go get github.com/kuetix/engine@latest

# 6. Create and build test project
kue create --name testapp --app-type cli
cd testapp
kue update
go build -o bin/testapp ./cmd/cli

# 7. Run test workflow
./bin/testapp workflows/common/example.wsl

Adding a New Module

In a kue-generated project:

# 1. Add the module
kue add module my_module

# 2. Edit the transition handler file
# modules/services/my_module/transitions/my_module.go

# 3. Update cache and rebuild
kue update
make build-cli

# 4. Run workflow
./runtime/bin/myapp-cli workflows/common/example.wsl

In engine source:

# 1. Create the module structure
mkdir -p modules/my_module/transitions

# 2. Create transition handler file
# (create modules/my_module/transitions/my_transitions.go)

# 3. Update module cache
kue update

# 4. Rebuild
make build

Troubleshooting

Common Issues

"Module not found"

# Solution: Update the module cache
kue update

"Workflow not found"

# Check workflow location
ls runtime/workflows/

# Workflows must be in runtime/workflows/<name>/

Build Errors

# Resolve dependencies
go mod tidy

# Verify Go version (1.21+ required)
go version

Installation​

Step 1: Add Engine as Go Module​

Step 2: Install kue CLI Tool​

Using Makefile (Recommended)​

Using install.sh​

kue​

Typical Workflow​

Commands​

kue create​

kue add​

kue add module​

kue add workflow​

kue add feature​

kue add solution​

kue add transition​

kue add package​

kue run​

kue register​

kue login​

kue logout​

kue profile​

kue profile get​

kue profile update​

kue package​

kue package add​

kue package update​

kue package publish​

kue package show​

kue package enable​

kue package list​

kue package list-local​

kue templates​

kue update​

kue show​

Running Your Application​

kue version​

Generated Project Structure​

Makefile​

runner.sh Script​

Environment Variables​

Build Commands​

Using Generated Project Makefile​

Building the Engine from Source​

Common Workflows​

Quick Start with kue​

Development Setup (Engine Source)​

Adding a New Module​

In a kue-generated project:​

In engine source:​

Troubleshooting​

Common Issues​

"Module not found"​

"Workflow not found"​

Build Errors​

See Also​

Installation

Step 1: Add Engine as Go Module

Step 2: Install kue CLI Tool

Using Makefile (Recommended)

Using install.sh

kue

Typical Workflow

Commands

kue create

kue add

kue add module

kue add workflow

kue add feature

kue add solution

kue add transition

kue add package

kue run

kue register

kue login

kue logout

kue profile

kue profile get

kue profile update

kue package

kue package add

kue package update

kue package publish

kue package show

kue package enable

kue package list

kue package list-local

kue templates

kue update

kue show

Running Your Application

kue version

Generated Project Structure

Makefile

runner.sh Script

Environment Variables

Build Commands

Using Generated Project Makefile

Building the Engine from Source

Common Workflows

Quick Start with kue

Development Setup (Engine Source)

Adding a New Module

In a kue-generated project:

In engine source:

Troubleshooting

Common Issues

"Module not found"

"Workflow not found"

Build Errors

See Also