Module Dependency CLI Commands

Invowk provides a set of invowk module commands for managing module dependencies declared in invowkmod.cue.

Command Overview

Command	Description
invowk module add	Resolve a dependency and print a requires entry
invowk module remove	Remove a dependency from the lock file
invowk module deps	List resolved dependencies
invowk module sync	Resolve dependencies from invowkmod.cue
invowk module update	Update dependencies to latest matching versions
invowk module vendor	Vendor dependencies into invowk_modules/ (partial)

invowk module add

Resolve a dependency and print the requires entry to add to invowkmod.cue.

Usage

invowk module add <git-url> <version> [flags]

Arguments

Argument	Description
git-url	Git repository URL (HTTPS or SSH)
version	Semantic version constraint

Flags

Flag	Description
--alias <name>	Custom namespace for the dependency
--path <path>	Subdirectory within the repository

Examples

# Add a dependency with caret version
invowk module add https://github.com/user/mod.invowkmod.git ^1.0.0

# Add with SSH URL
invowk module add git@github.com:user/mod.invowkmod.git ~2.0.0

# Add with custom alias
invowk module add https://github.com/user/common.invowkmod.git ^1.0.0 --alias tools

# Add from monorepo subdirectory
invowk module add https://github.com/user/monorepo.invowkmod.git ^1.0.0 --path modules/cli

Output

Add Module Dependency

• Resolving https://github.com/user/mod.invowkmod.git@^1.0.0...
✓ Module added successfully

• Git URL:   https://github.com/user/mod.invowkmod.git
• Version:   ^1.0.0 → 1.2.3
• Namespace: mod@1.2.3
• Cache:     /home/user/.invowk/modules/github.com/user/mod.invowkmod/1.2.3

• To use this module, add to your invowkmod.cue:

requires: [
    {
        git_url: "https://github.com/user/mod.invowkmod.git"
        version: "^1.0.0"
    },
]

note

invowk module add does not edit invowkmod.cue for you. Copy the printed requires entry into your module metadata, then run invowk module sync.

invowk module remove

Remove a dependency from the lock file.

Usage

invowk module remove <git-url>

Arguments

Argument	Description
git-url	Git repository URL to remove

Examples

invowk module remove https://github.com/user/mod.invowkmod.git

Output

Remove Module Dependency

• Removing https://github.com/user/mod.invowkmod.git...
✓ Module removed from lock file

• Don't forget to remove the requires entry from your invowkmod.cue

note

This command only removes the dependency from the lock file. You must manually remove the requires entry from invowkmod.cue. Cached files are not deleted.

invowk module deps

List all resolved dependencies from the lock file.

Usage

invowk module deps

Output

Module Dependencies

• Found 2 module dependency(ies)

✓ build-tools@2.3.1
   Git URL:  https://github.com/company/build-tools.invowkmod.git
   Version:  ^2.0.0 → 2.3.1
   Commit:   abc123def456
   Cache:    /home/user/.invowk/modules/github.com/company/build-tools.invowkmod/2.3.1

✓ deploy-utils@1.5.2
   Git URL:  https://github.com/company/deploy-tools.invowkmod.git
   Version:  ~1.5.0 → 1.5.2
   Commit:   789xyz012abc
   Cache:    /home/user/.invowk/modules/github.com/company/deploy-tools.invowkmod/1.5.2

No Dependencies

Module Dependencies

• No module dependencies found

• To add modules, use: invowk module add <git-url> <version>

invowk module sync

Sync all dependencies declared in invowkmod.cue. This reads the requires field, resolves version constraints, downloads modules, and updates the lock file.

Usage

invowk module sync

Output

Sync Module Dependencies

• Found 2 requirement(s) in invowkmod.cue

✓ build-tools@2.3.1 → 2.3.1
✓ deploy-utils@1.5.2 → 1.5.2

✓ Lock file updated: invowkmod.lock.cue

No Requirements

Sync Module Dependencies

• No requires field found in invowkmod.cue

invowk module update

Update dependencies to their latest versions matching the declared constraints.

Usage

invowk module update [git-url]

Arguments

Argument	Description
git-url	(Optional) Specific dependency to update

Examples

# Update all modules
invowk module update

# Update a specific module
invowk module update https://github.com/user/mod.invowkmod.git

Output

Update Module Dependencies

• Updating all modules...

✓ build-tools@2.3.1 → 2.4.0
✓ deploy-utils@1.5.2 → 1.5.3

✓ Lock file updated: invowkmod.lock.cue

No Updates

Update Module Dependencies

• Updating all modules...
• No modules to update

invowk module vendor

Vendor dependencies into the invowk_modules/ directory for offline use and distribution.

Usage

invowk module vendor [module-path]

Output

Vendor Module Dependencies

• Found 2 requirement(s) in invowkmod.cue
• Vendor directory: /home/user/project/invowk_modules

! Vendoring is not yet fully implemented

• The following dependencies would be vendored:
   • https://github.com/example/common.invowkmod.git@^1.0.0
   • https://github.com/example/deploy.invowkmod.git@~1.5.0

note

Vendoring is currently a preview. The command reports what would be vendored and creates the directory, but does not fetch dependencies yet.

Common Workflows

Initial Setup

# 1. Resolve dependencies
invowk module add https://github.com/company/build-tools.invowkmod.git ^2.0.0 --alias build
invowk module add https://github.com/company/deploy-tools.invowkmod.git ~1.5.0 --alias deploy

# 2. Add requires to invowkmod.cue manually or verify
cat invowkmod.cue

# 3. Sync to generate lock file
invowk module sync

# 4. Commit the lock file
git add invowkmod.lock.cue
git commit -m "Add module dependencies"

Fresh Clone

# On a fresh clone, sync downloads all modules
git clone https://github.com/yourorg/project.git
cd project
invowk module sync

Regular Updates

# Update all modules periodically
invowk module update

# Review changes
git diff invowkmod.lock.cue

# Commit if tests pass
git add invowkmod.lock.cue
git commit -m "Update module dependencies"

Troubleshooting

# List current dependencies to verify state
invowk module deps

# Re-sync if something seems wrong
invowk module sync

# Check commands are available
invowk cmd

Environment Variables

Variable	Description
INVOWK_MODULES_PATH	Override module cache directory
GITHUB_TOKEN	GitHub authentication
GITLAB_TOKEN	GitLab authentication
GIT_TOKEN	Generic Git authentication

Exit Codes

Code	Meaning
0	Success
1	General error
1	Module not found (for remove)
1	No invowkmod.cue found (for sync)
1	Version resolution failed
1	Git clone/fetch failed