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 invowkmod.cue metadata with optional invowkfile.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 .invowkmod suffix:

mytools.invowkmod/
├── invowkmod.cue          # Required: module metadata
├── invowkfile.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.invowkmod/
├── invowkmod.cue
└── invowkfile.cue

Use the Module

Modules are automatically discovered from:

1. Current directory (invowkfile and local modules)
2. Configured includes entries
3. ~/.invowk/cmds/ (user modules — *.invowkmod only, non-recursive)

# 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.invowkmod

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

Module Structure

Required Files

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

Optional Contents

• invowkfile.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.invowkmod/
├── invowkmod.cue
├── invowkfile.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 .invowkmod	mytools.invowkmod	mytools
Start with letter	mytools.invowkmod	123tools.invowkmod
Alphanumeric + dots	com.example.invowkmod	my-tools.invowkmod

RDNS Naming

Recommended for shared modules:

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

Script Paths

Reference scripts relative to module root with forward slashes:

// Inside mytools.invowkmod/invowkfile.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 list	List discovered modules
invowk module archive	Create zip archive
invowk module import	Install from zip/URL
invowk module vendor	Vendor module dependencies locally
invowk module add	Add a module dependency (resolves, caches, updates lock file and invowkmod.cue)
invowk module remove	Remove a module dependency (updates lock file and invowkmod.cue)
invowk module sync	Synchronize dependencies from invowkmod.cue to lock file
invowk module update	Update module dependencies to latest matching versions
invowk module deps	Show dependency tree

Discovery

Modules are discovered from these locations:

1. Current directory invowkfile (highest priority)
2. Local modules (*.invowkmod in current directory)
3. Configured includes (module paths from config)
4. User commands directory (~/.invowk/cmds/ — *.invowkmod only, non-recursive)

Commands appear in invowk cmd output with their source:

Available Commands

From invowkfile:
  build - Build the project [native*]

From com.example.utilities.invowkmod:
  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