Skip to main content
Version: 0.1.0-alpha.2

Invkmod Schema Reference

:::warning Alpha — Schema May Change The invkmod schema is still evolving. Fields, types, and validation rules may change between releases as we stabilize the format. Always check the changelog when upgrading. :::

Complete reference for invkmod.cue, the module metadata file. Module metadata is validated as a closed struct, so unknown fields cause a validation error.

Root Structure​

Every module must include an invkmod.cue file with this structure:

#Invkmod: {
    module:       string               // Required - module identifier
    version?:     string               // Optional - metadata version (e.g., "1.0")
    description?: string               // Optional - module description
    requires?:    [...#ModuleRequirement] // Optional - dependencies
}

module​

Type: string (pattern: ^[a-zA-Z][a-zA-Z0-9]*(\.[a-zA-Z][a-zA-Z0-9]*)*$) Required: Yes

The module identifier. It must match the folder name prefix (before .invkmod).

module: "mytools"
module: "com.company.devtools"
module: "io.github.username.cli"

version​

Type: string (pattern: ^[0-9]+\.[0-9]+$) Required: No

Module metadata version. Current version is "1.0".

description​

Type: string Required: No

A short summary of the module's purpose.

requires​

Type: [...#ModuleRequirement] Required: No

List of module dependencies from Git repositories.

requires: [
    {
        git_url: "https://github.com/example/common.invkmod.git"
        version: "^1.0.0"
        alias: "common"
    },
]

ModuleRequirement​

Defines a single dependency entry:

#ModuleRequirement: {
    git_url: string
    version: string
    alias?:  string
    path?:   string
}

git_url​

Type: string Required: Yes

Git repository URL (HTTPS or SSH). The repository must contain a module.

version​

Type: string Required: Yes

Semantic version constraint used to resolve a Git tag.

alias​

Type: string Required: No

Overrides the default namespace for this dependency (must follow module naming rules).

path​

Type: string Required: No

Subdirectory within the repository that contains the module. Must be relative and cannot contain path traversal sequences.