Modules Overview

Alpha — Module Format May Change

The module format and structure are still being finalized. While we aim for backwards compatibility, breaking changes may occur before the 1.0 release. If you're distributing modules externally, be prepared to update them when upgrading Invowk™.

Modules are self-contained folders that bundle invkmod.cue metadata with optional invkfile.cue commands and any script files they reference. They're perfect for sharing commands, creating reusable toolkits, and distributing automation across teams.

What is a Module?

A module is a directory with the .invkmod suffix:

mytools.invkmod/
├── invkmod.cue          # Required: module metadata
├── invkfile.cue          # Optional: command definitions
├── scripts/              # Optional: script files
│   ├── build.sh
│   └── deploy.sh
└── templates/             # Optional: other resources
    └── config.yaml

Why Use Modules?

• Portability: Share a complete command set as a single folder
• Self-contained: Scripts are bundled with the module
• Cross-platform: Forward slash paths work everywhere
• Namespace isolation: RDNS naming prevents conflicts
• Easy distribution: Zip, share, unzip

Quick Start

Create a Module

invowk module create mytools

Creates:

mytools.invkmod/
├── invkmod.cue
└── invkfile.cue

Use the Module

Modules are automatically discovered from:

1. Current directory
2. ~/.invowk/cmds/ (user commands)
3. Configured search paths

# List commands (module commands appear automatically)
invowk cmd

# Run a module command
invowk cmd mytools hello

Share the Module

# Create a zip archive
invowk module archive mytools.invkmod

# Share the zip file
# Recipients import with:
invowk module import mytools.invkmod.zip

Module Structure

Required Files

• invkmod.cue: Module metadata (name, version, dependencies)

Optional Contents

• invkfile.cue: Command definitions (omit for library-only modules)
• Scripts: Shell scripts, Python files, etc.
• Templates: Configuration templates
• Data: Any supporting files

Example Structure

com.example.devtools.invkmod/
├── invkmod.cue
├── invkfile.cue
├── scripts/
│   ├── build.sh
│   ├── deploy.sh
│   └── utils/
│       └── helpers.sh
├── templates/
│   ├── Dockerfile.tmpl
│   └── config.yaml.tmpl
└── README.md

Module Naming

Module folder names follow these rules:

Rule	Valid	Invalid
End with .invkmod	mytools.invkmod	mytools
Start with letter	mytools.invkmod	123tools.invkmod
Alphanumeric + dots	com.example.invkmod	my-tools.invkmod

RDNS Naming

Recommended for shared modules:

com.company.projectname.invkmod
io.github.username.toolkit.invkmod
org.opensource.utilities.invkmod

Script Paths

Reference scripts relative to module root with forward slashes:

// Inside mytools.invkmod/invkfile.cue
cmds: [
    {
        name: "build"
        implementations: [{
            script: "scripts/build.sh"  // Relative to module root
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }]
    },
    {
        name: "deploy"
        implementations: [{
            script: "scripts/utils/helpers.sh"  // Nested path
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }]
    }
]

Important:

• Always use forward slashes (/)
• Paths are relative to module root
• No absolute paths allowed
• Can't escape module directory (../ is invalid)

Module Commands

Command	Description
invowk module create	Create a new module
invowk module validate	Validate module structure
invowk module list	List discovered modules
invowk module archive	Create zip archive
invowk module import	Install from zip/URL

Discovery

Modules are discovered from these locations:

1. Current directory (highest priority)
2. User commands (~/.invowk/cmds/)
3. Search paths (from config)

Commands appear in invowk cmd --list with their source:

Available Commands

From current directory:
  mytools build - Build the project [native*]

From user commands (~/.invowk/cmds):
  com.example.utilities hello - Greeting [native*]

Next Steps

• Creating Modules - Scaffold and structure modules
• Validating - Ensure module integrity
• Distributing - Share modules with others
• Module Dependencies - Use other modules in your module