Skip to main content
Version: Next

Module Dependencies Overview

Alpha — Module Dependencies May Change

Module dependencies are still being refined. While we aim for backwards compatibility, breaking changes may occur before the 1.0 release. Lock files keep builds reproducible, but resolution behavior may evolve.

Module dependencies let a module pull in commands from other modules hosted in Git repositories. Dependencies are declared in invowkmod.cue under requires and resolved into invowkmod.lock.cue.

What are Module Dependencies?​

Module dependencies are external modules that your module depends on. They are:

  • Hosted in Git repositories (GitHub, GitLab, Bitbucket, etc.)
  • Versioned with semantic versioning (tags like v1.2.3 or 1.2.3)
  • Cached locally for offline use and performance
  • Namespaced by module ID or alias to prevent collisions

Quick Start​

1. (Optional) Resolve a Dependency​

invowk module add resolves a dependency, updates invowkmod.lock.cue, and auto-edits invowkmod.cue to add the requires entry when the file exists:

invowk module add https://github.com/example/common.invowkmod.git ^1.0.0

2. Declare in invowkmod.cue​

module: "com.example.mytools"
version: "1.0.0"
description: "My tools"

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

3. Sync Dependencies​

invowk module sync

4. Verify Resolved Dependencies​

invowk module deps

Namespaces and Aliases​

When a dependency module is installed in a discovery path, run its commands with the module ID (or alias if you set one):

# Default namespace includes the resolved version
invowk cmd com.example.common@1.2.3 build

# With alias
invowk cmd common build

How It Works​

  1. Declaration: Dependencies are listed in invowkmod.cue under requires
  2. Resolution: invowk module sync resolves version constraints to concrete versions
  3. Download: Modules are cloned from Git and cached locally
  4. Lock file: Resolved versions are written to invowkmod.lock.cue
  5. Discovery: Commands are available via the module namespace when the dependency is installed
Explicit-Only Dependencies (Go-Style)

Invowk uses an explicit-only dependency model, similar to 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 fails with actionable errors if transitive dependencies are missing.
  • invowk module tidy auto-adds missing transitive dependencies to your invowkmod.cue.

When declaring depends_on.cmds, commands in a module can only reference commands from:

  1. The same module
  2. Globally installed modules (your discovery paths)
  3. Modules declared directly in that module's requires list

This scope is enforced at validation time (during invowk module sync and before command execution). It does not intercept runtime subprocess calls within scripts.

Module Cache​

Module dependencies are cached in ~/.invowk/modules/ by default:

~/.invowk/modules/
├── sources/
│   └── github.com/
│       └── example/
│           └── common.invowkmod/
└── github.com/
    └── example/
        └── common.invowkmod/
            └── 1.2.3/
                ├── invowkmod.cue
                └── invowkfile.cue

Override the cache location:

export INVOWK_MODULES_PATH=/custom/cache/path

Next Steps​