Declaring Dependencies

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

Basic Syntax

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

requires: [
    {
        git_url: "https://github.com/example/common.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 command source ID for commands
path	No	Subdirectory within the repository

git_url

The Git repository URL. Supports both HTTPS and SSH formats. The repository name is only the source location; it does not have to end in .invowkmod and does not define the module identity.

When path is omitted, the repository root must contain both invowkmod.cue and invowkfile.cue. If the module lives in a child directory, declare path explicitly.

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

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

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

    // Self-hosted
    {git_url: "https://git.example.com/user/tools.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 automatically resolves Git tags with or without the v prefix — both v1.2.3 and 1.2.3 tags are matched when fetching.

However, the version constraint value in invowkmod.cue must not include the v prefix. Write version: "^1.2.3", not version: "^v1.2.3".

Each requirement accepts one constraint expression. Use version: ">=1.0.0" or version: "<=2.0.0" as a single bound; compound ranges such as ">=1.0.0 <2.0.0" are rejected.

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

alias

Override the default command source ID for the dependency's commands:

requires: [
    // Default command source ID: io.example.common
    {git_url: "https://github.com/user/common.git", version: "^1.0.0"},

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

The default command source ID comes from invowkmod.cue: module, not from the Git repository basename. An alias changes only the command namespace used for execution and disambiguation; it does not change the canonical module identity, cache directory, vendor directory, or lock module_id.

Usage with alias:

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

path

For monorepos containing multiple modules, specify the subdirectory:

requires: [
    {
        git_url: "https://github.com/user/monorepo.git"
        version: "^1.0.0"
        path: "modules/io.example.cli.invowkmod"
    },
    {
        git_url: "https://github.com/user/monorepo.git"
        version: "^1.0.0"
        path: "modules/io.example.deploy.invowkmod"
        alias: "deploy"
    },
]

Paths must be relative, cannot contain .. or absolute paths, and must point directly to a directory whose basename ends in .invowkmod. For explicit subpaths, the basename prefix must match the selected module's module value. For example, modules/io.example.cli.invowkmod must contain module: "io.example.cli".

Synced and vendored dependencies are materialized locally as <module-id>.invowkmod, even when the source repository is named something ordinary like tools.git.

Multiple Dependencies

Declare multiple dependencies in the requires array:

requires: [
    {
        git_url: "https://github.com/company/build-tools.git"
        version: "^2.0.0"
        alias: "build"
    },
    {
        git_url: "https://github.com/company/deploy-tools.git"
        version: "~1.5.0"
        alias: "deploy"
    },
    {
        git_url: "https://github.com/company/test-utils.git"
        version: ">=1.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

Invowk uses an explicit-only dependency model (like Go modules): every module in the dependency tree must be declared in your root invowkmod.cue. If module A requires module B, and B requires C, then C must also be declared in your invowkmod.cue.

• invowk module sync will fail with actionable errors listing any missing transitive dependencies.
• invowk module tidy scans resolved modules and auto-adds missing transitive dependencies to your invowkmod.cue.

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.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.git"
    version: "^2.0.0"
    alias: "build"
}

3. Commit Your Lock File

The invowkmod.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  // Relative subdirectory; traversal is rejected after decode
}