kalo-cli

README

Kalo CLI

A modern, powerful CLI tool for running Morphe compilation plugins using WebAssembly (WASM).

Overview

Kalo CLI enables the seamless compilation of Morphe models, entities, enums, and structures across different formats using WASM plugins. The tool is designed to be extensible, supporting multiple input and output formats through a flexible configuration system.

Features

• WASM Plugin Support: Run compiled plugins in a secure WASM sandbox
• Flexible Configuration: Define input and output specifications in a YAML configuration file
• Environment Variable Support: Configure plugins using environment variables
• Multiple Format Support: Transform between different formats (YAML, Go, PostgreSQL, TypeScript, etc.)
• Dotenv Integration: Load environment variables from .env files

Installation

Quick Install (Recommended)

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/kalo-build/kalo-cli/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/kalo-build/kalo-cli/main/install.ps1 | iex

Homebrew (macOS / Linux)

# Install directly (auto-taps the repo)
brew install kalo-build/tap/kalo

# Or manually tap first
brew tap kalo-build/tap
brew install kalo

Scoop (Windows)

# Add the bucket (one-time)
scoop bucket add kalo https://github.com/kalo-build/scoop-bucket

# Install
scoop install kalo

Go Install

go install github.com/kalo-build/kalo-cli/cmd/kalo@latest

Manual Download

Download the latest release from GitHub Releases.

Build from Source

git clone https://github.com/kalo-build/kalo-cli.git
cd kalo-cli
go build -o kalo ./cmd/kalo

Usage

# Install all plugins from kalo.yaml (like npm install)
kalo install

# List available pipelines
kalo list

# Run a pipeline by name
kalo run compile

# Run a pipeline by alias (if configured)
kalo run up        # alias for migrate-up
kalo run down      # alias for migrate-down

# Run the default compile pipeline
kalo compile

# Install a specific plugin (adds to kalo.yaml if not present)
kalo plugin install @kalo-build/plugin-morphe-go-struct

Commands

Command	Description
kalo install	Download all plugins from kalo.yaml (like npm install)
kalo list	List all available pipelines with descriptions
kalo run <name>	Run a pipeline or plugin by name or alias
kalo compile	Shorthand for kalo run compile
kalo plugin install <plugin>	Install a specific plugin from registry

Configuration

Kalo CLI uses a YAML configuration file (kalo.yaml by default) to define stores, plugins, and pipelines.

Stores

Stores define data sources and destinations:

stores:
  # Local filesystem store
  KA_MIGRATIONS:
    format: "KA:PSQL:MIGRATION1"
    type: "localFileSystem"
    options:
      path: "./migrations"

  # Git repository store (extracts files from a git ref)
  KA_GIT_MAIN:
    format: "KA:MO1:YAML1"
    type: "gitRepository"
    options:
      repoRoot: "."
      ref: "main"
      subPath: "morphe/registry"

  # Cloud SQL database store
  DB_MAIN:
    format: "KA:PSQL:LIVE"
    type: "cloudSqlDatabase"
    options:
      provider: "gcp"
      connection: "$DATABASE_URL"

Pipelines

Pipelines define multi-stage workflows:

pipelines:
  compile:
    description: "Compile Morphe schemas to PSQL and Go"
    stages:
    - name: "psql-types"
      steps:
        - "plugin: @kalo-build/plugin-morphe-psql-types"

  migrate-up:
    description: "Apply pending migrations"
    alias: "up"  # Enables: kalo run up
    stages:
    - name: "up"
      steps:
        - "plugin: @kalo-build/plugin-morphe-db-manager"
      config:
        mode: "up"

Plugins

Configure plugin inputs, outputs, and settings:

plugins:
  "@kalo-build/plugin-morphe-db-manager":
    version: "v1.0.0"
    inputs:
      schema:
        format: "KA:MO1:PSQL1"
        store: "KA_MO_PSQL"
      migrations:
        format: "KA:PSQL:MIGRATION1"
        store: "KA_MIGRATIONS"
    output:
      format: "KA:PSQL:LIVE"
      store: "DB_MAIN"

Building WASM Plugins

To create a WASM plugin for Kalo CLI:

# Build a Go plugin for WASM
GOOS=wasip1 GOARCH=wasm go build -o plugins/morphe-go-struct.wasm ./path/to/plugin

Releasing New Versions

Releases are automated via GitHub Actions using GoReleaser. To create a new release:

# Create and push a version tag
git tag v1.2.3
git push origin v1.2.3

This triggers the release workflow which:

1. Builds binaries for Linux, macOS, and Windows (amd64/arm64)
2. Creates a GitHub Release with the binaries
3. Updates Homebrew tap and Scoop bucket formulas

Version Format

Use semantic versioning:

• v1.0.0 - Major release
• v1.1.0 - Minor release (new features)
• v1.1.1 - Patch release (bug fixes)

Prereleases

Tags with prerelease suffixes are automatically marked as prereleases on GitHub:

# Prerelease examples
git tag v1.0.0-alpha
git tag v1.0.0-beta.1
git tag v1.0.0-rc.1
git tag v0.0.1-dev.123

Prereleases:

• Are marked as "Pre-release" on GitHub Releases
• Are not installed by the quick install scripts (which fetch "latest")
• Are not pushed to Homebrew/Scoop (package managers only get stable releases)

To test a prerelease manually, download from the Releases page.

Environment Variables

Kalo CLI supports loading environment variables from a .env file, which can be useful for setting up paths and other configuration values.

Example .env file:

BASE_DIR=/path/to/morphe/files

License

MIT License