Skip to main content
Version: Next

Module Dependencies Overview

:::warning 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
  • Published under a command source ID derived from the dependency 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.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.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, its commands publish under a command source ID. The default source ID is the dependency module ID; alias overrides it. Run the simple command name when unique, or use @<source> / --ivk-from <source> to disambiguate:

# Default command source ID
invowk cmd common build

# Disambiguate when another source also defines "build"
invowk cmd @common build
invowk cmd --ivk-from common build

# With alias
invowk cmd tools 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 command source ID when the dependency is installed

:::note 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 user command modules under ~/.invowk/cmds/
  3. Modules declared directly in that module's requires list

This scope is enforced by depends_on.cmds validation 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/
└── github.com/
    └── example/
        └── common/
            └── 1.2.3/
                └── io.example.common.invowkmod/
                    ├── invowkmod.cue
                    └── invowkfile.cue

Override the cache location:

export INVOWK_MODULES_PATH=/custom/cache/path

Next Steps​