Declaring Dependencies

Module dependencies are declared in the requires field of invkmod.cue. This page covers the syntax and options available.

Basic Syntax

module: "com.example.mytools"
version: "1.0"

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

Requirement Fields

Field	Required	Description
git_url	Yes	Git repository URL (HTTPS or SSH)
version	Yes	Semantic version constraint
alias	No	Custom namespace for commands
path	No	Subdirectory within the repository

git_url

The Git repository URL. Supports both HTTPS and SSH formats. The repository must contain a module (either a .invkmod directory or an invkmod.cue at the root).

requires: [
    // HTTPS (works with public repos or GITHUB_TOKEN)
    {git_url: "https://github.com/user/tools.invkmod.git", version: "^1.0.0"},

    // SSH (requires SSH key in ~/.ssh/)
    {git_url: "git@github.com:user/tools.invkmod.git", version: "^1.0.0"},

    // GitLab
    {git_url: "https://gitlab.com/user/tools.invkmod.git", version: "^1.0.0"},

    // Self-hosted
    {git_url: "https://git.example.com/user/tools.invkmod.git", version: "^1.0.0"},
]

version

Semantic version constraint. The repository must have Git tags matching the constraint.

Version Constraint Formats

Format	Description	Matches
^1.2.3	Compatible (same major)	>=1.2.3 <2.0.0
~1.2.3	Approximately (same minor)	>=1.2.3 <1.3.0
>=1.0.0	Greater than or equal	1.0.0, 1.5.0, 2.0.0, ...
>1.0.0	Greater than	1.0.1, 1.5.0, 2.0.0, ...
<2.0.0	Less than	1.9.9, 1.0.0, 0.5.0, ...
<=2.0.0	Less than or equal	2.0.0, 1.9.9, 1.0.0, ...
1.2.3	Exact version	Only 1.2.3

Version Tag Formats

Invowk accepts tags with or without the v prefix:

• v1.2.3 and 1.2.3 are both valid
• When resolving, both formats are tried automatically

requires: [
    // Invowk tries both v1.0.0 and 1.0.0
    {git_url: "https://github.com/user/tools.invkmod.git", version: "^1.0.0"},
]

alias

Override the default namespace for the dependency's commands:

requires: [
    // Default namespace: common@1.2.3
    {git_url: "https://github.com/user/common.invkmod.git", version: "^1.0.0"},

    // Custom namespace: tools
    {
        git_url: "https://github.com/user/common.invkmod.git"
        version: "^1.0.0"
        alias: "tools"
    },
]

Usage with alias:

# Instead of: invowk cmd common@1.2.3 build
invowk cmd tools build

path

For monorepos containing multiple modules, specify the subdirectory:

requires: [
    {
        git_url: "https://github.com/user/monorepo.invkmod.git"
        version: "^1.0.0"
        path: "modules/cli-tools"
    },
    {
        git_url: "https://github.com/user/monorepo.invkmod.git"
        version: "^1.0.0"
        path: "modules/deploy-utils"
        alias: "deploy"
    },
]

Paths must be relative and cannot contain .. or absolute paths.

Multiple Dependencies

Declare multiple dependencies in the requires array:

requires: [
    {
        git_url: "https://github.com/company/build-tools.invkmod.git"
        version: "^2.0.0"
        alias: "build"
    },
    {
        git_url: "https://github.com/company/deploy-tools.invkmod.git"
        version: "~1.5.0"
        alias: "deploy"
    },
    {
        git_url: "https://github.com/company/test-utils.invkmod.git"
        version: ">=1.0.0 <2.0.0"
    },
]

Authentication

SSH Keys

For SSH URLs (git@...), invowk uses keys from ~/.ssh/:

1. ~/.ssh/id_ed25519 (preferred)
2. ~/.ssh/id_rsa
3. ~/.ssh/id_ecdsa

HTTPS Tokens

For private HTTPS repositories, set environment variables:

# GitHub
export GITHUB_TOKEN=ghp_xxxx

# GitLab
export GITLAB_TOKEN=glpat-xxxx

# Generic (any Git server)
export GIT_TOKEN=your-token

Transitive Dependencies

Dependencies can declare their own dependencies. When you sync, invowk resolves the full dependency tree and records it in the lock file:

com.example.app
├── common-tools@1.2.3
│   └── logging-utils@2.0.0
└── deploy-utils@1.5.0
    └── common-tools@1.2.3  (shared)

Circular Dependency Detection

Invowk detects and reports circular dependencies:

Error: circular dependency detected: https://github.com/user/module-a.invkmod.git

Best Practices

1. Use Caret for Most Dependencies

// Good: allows patch and minor updates
{git_url: "...", version: "^1.0.0"}

// Too strict: no updates allowed
{git_url: "...", version: "1.0.0"}

2. Use Aliases for Cleaner Namespaces

{
    git_url: "https://github.com/company/company-internal-build-tools.invkmod.git"
    version: "^2.0.0"
    alias: "build"
}

3. Commit Your Lock File

The invkmod.lock.cue file should be committed to version control for reproducible builds.

4. Update Regularly

invowk module update

Schema Reference

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