Development Commands

This guide covers CLI commands commonly used during module development.

generate component

Generate a new component with boilerplate code:

tinysystems generate component [name] [flags]

Flags:
  --package    Package name (default: component name)
  --template   Component template (basic, stateful, server)

Examples

# Basic component
tinysystems generate component transformer

# Stateful component with specific package
tinysystems generate component counter --package mypackage --template stateful

# HTTP server component
tinysystems generate component api-server --template server

Generated Files

components/transformer/
├── component.go       # Main component implementation
├── types.go          # Input/Output/Settings types
├── component_test.go # Unit tests
└── README.md         # Component documentation

Generated Code

// component.go
package transformer

import (
    "context"

    "github.com/tiny-systems/module/api/v1alpha1"
    "github.com/tiny-systems/module/module"
    "github.com/tiny-systems/module/pkg/schema"
)

type Component struct {
    settings Settings
}

func (c *Component) GetInfo() module.Info {
    return module.Info{
        Name:        "transformer",
        Description: "Transformer component",
        Icon:        "IconBox",
        Tags:        []string{"utility"},
    }
}

func (c *Component) Ports() []module.Port {
    return []module.Port{
        {
            Name:     v1alpha1.SettingsPort,
            Label:    "Settings",
            Source:   true,
            Position: module.PositionTop,
            Schema:   schema.FromGo(Settings{}),
        },
        {
            Name:     "input",
            Label:    "Input",
            Source:   true,
            Position: module.PositionLeft,
            Schema:   schema.FromGo(Input{}),
        },
        {
            Name:     "output",
            Label:    "Output",
            Source:   false,
            Position: module.PositionRight,
            Schema:   schema.FromGo(Output{}),
        },
    }
}

func (c *Component) Handle(ctx context.Context, output module.Handler, port string, msg any) error {
    switch port {
    case v1alpha1.SettingsPort:
        c.settings = msg.(Settings)
        return nil

    case "input":
        input := msg.(Input)
        // TODO: Implement transformation logic
        return output(ctx, "output", Output{
            Result: input.Data,
        })
    }
    return nil
}

func (c *Component) Instance() module.Component {
    return &Component{}
}

generate schema

Generate JSON Schema from Go types:

tinysystems generate schema [type-name] [flags]

Flags:
  --output    Output file (default: stdout)
  --package   Package to search for type

Examples

# Generate schema for Settings type
tinysystems generate schema Settings --package ./components/mycomponent

# Output to file
tinysystems generate schema Input --output schema.json

generate helm

Generate Helm chart for module:

tinysystems generate helm [flags]

Flags:
  --output    Output directory (default: ./charts)
  --name      Chart name (default: module name)

Generated Structure

charts/my-module/
├── Chart.yaml
├── values.yaml
├── templates/
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── serviceaccount.yaml
│   ├── rbac.yaml
│   └── _helpers.tpl
└── crds/
    ├── tinymodule.yaml
    ├── tinynode.yaml
    └── tinysignal.yaml

run

Run module locally for development:

tinysystems run [flags]

Flags:
  --port        gRPC port (default: 50051)
  --debug       Enable debug logging
  --watch       Watch for file changes and restart
  --kubeconfig  Kubeconfig path
  --namespace   Kubernetes namespace to watch
  --leader      Force leader mode

Examples

# Basic local run
tinysystems run

# With watch mode for development
tinysystems run --watch --debug

# Force leader mode for testing
tinysystems run --leader

# Connect to remote cluster
tinysystems run --kubeconfig ~/.kube/production-config --namespace prod

Output

INFO  Starting module                module=my-module version=1.0.0
INFO  gRPC server listening         address=:50051
INFO  Connected to Kubernetes       context=minikube
INFO  Watching TinyNodes            namespace=tinysystems
INFO  Components registered         count=3
      - transformer
      - filter
      - aggregator

build

Build container image:

tinysystems build [flags]

Flags:
  --tag         Image tag (required)
  --push        Push to registry after build
  --platform    Target platforms (default: linux/amd64)
  --builder     Builder to use (docker, buildx, ko)
  --no-cache    Build without cache
  --dockerfile  Custom Dockerfile path

Examples

# Build for local testing
tinysystems build --tag my-module:dev

# Build and push to registry
tinysystems build --tag registry.io/myorg/my-module:v1.0.0 --push

# Multi-platform build
tinysystems build --tag my-module:v1.0.0 --platform linux/amd64,linux/arm64 --push

# Using ko for faster builds
tinysystems build --tag my-module:v1.0.0 --builder ko

test

Run component tests:

tinysystems test [flags]

Flags:
  --coverage    Generate coverage report
  --verbose     Verbose output
  --race        Enable race detector
  --component   Test specific component only

Examples

# Run all tests
tinysystems test

# With coverage
tinysystems test --coverage

# Specific component
tinysystems test --component transformer

# Verbose with race detection
tinysystems test --verbose --race

lint

Lint module code:

tinysystems lint [flags]

Flags:
  --fix         Auto-fix issues
  --strict      Strict mode

Checks Performed

• Component interface implementation
• Port schema validation
• Settings structure
• Error handling patterns
• Best practices

validate

Validate module configuration:

tinysystems validate [flags]

Flags:
  --config    Config file to validate

Validation Checks

• Module name format
• Version format
• Component uniqueness
• Port name uniqueness
• Schema validity

docs

Generate documentation:

tinysystems docs [flags]

Flags:
  --output    Output directory
  --format    Format (markdown, html)

Generated Docs

• Component reference
• Port schemas
• Settings reference
• Usage examples

Development Workflow

Typical Session

# 1. Create component
tinysystems generate component my-processor

# 2. Implement logic
vim components/my-processor/component.go

# 3. Run tests
tinysystems test --component my-processor

# 4. Run locally
tinysystems run --watch --debug

# 5. Build image
tinysystems build --tag my-module:dev

# 6. Deploy for testing
tinysystems deploy --image my-module:dev --namespace dev

Next Steps

• Module Scaffold - Project templates
• Local Testing - Testing strategies
• Building Modules - Production builds