Dependencies Overview

Dependencies let you declare what your command needs before it runs. Invowk™ validates all dependencies upfront and provides clear error messages when something's missing.

Why Declare Dependencies?

Without dependency checks:

$ invowk cmd build
./scripts/build.sh: line 5: go: command not found

With dependency checks:

$ invowk cmd build

✗ Dependencies not satisfied

Command 'build' has unmet dependencies:

Missing Tools:
  • go - not found in PATH

Install the missing tools and try again.

Much better! You know exactly what's wrong before anything runs.

Dependency Types

Invowk supports six types of dependencies:

Type	Checks For
tools	Binaries in PATH
filepaths	Files or directories
cmds	Other Invowk commands
capabilities	System capabilities
env_vars	Environment variables
custom_checks	Custom validation scripts

Basic Syntax

Dependencies are declared in the depends_on block:

{
    name: "build"
    depends_on: {
        tools: [
            {alternatives: ["go"]}
        ]
        filepaths: [
            {alternatives: ["go.mod"]}
        ]
    }
    implementations: [...]
}

The Alternatives Pattern

Every dependency uses an alternatives list with OR semantics:

// ANY of these tools satisfies the dependency
tools: [
    {alternatives: ["podman", "docker"]}
]

// ANY of these files satisfies the dependency
filepaths: [
    {alternatives: ["config.yaml", "config.json", "config.toml"]}
]

If any alternative is found, the dependency is satisfied. Invowk uses early return - it stops checking as soon as one matches.

Validation Order

Dependencies are validated in this order:

1. env_vars - Environment variables (checked first!)
2. tools - Binaries in PATH
3. filepaths - Files and directories
4. capabilities - System capabilities
5. custom_checks - Custom validation scripts
6. cmds - Other Invowk commands

Environment variables are validated first, before Invowk sets any command-level environment. This ensures you're checking the user's actual environment.

Scope Levels

Dependencies can be declared at three levels:

Root Level (Global)

Applies to all commands in the invowkfile:

depends_on: {
    tools: [{alternatives: ["git"]}]  // Required by all commands
}

cmds: [...]

Command Level

Applies to a specific command:

{
    name: "build"
    depends_on: {
        tools: [{alternatives: ["go"]}]  // Required by this command
    }
    implementations: [...]
}

Implementation Level

Applies to a specific implementation:

{
    name: "build"
    implementations: [
        {
            script: "go build ./..."
            runtimes: [{name: "container", image: "golang:1.26"}]
            platforms: [{name: "linux"}]
            depends_on: {
                // Validated INSIDE the container
                tools: [{alternatives: ["go"]}]
            }
        }
    ]
}

Scope Inheritance

Dependencies are combined across levels:

// Root level: requires git
depends_on: {
    tools: [{alternatives: ["git"]}]
}

cmds: [
    {
        name: "build"
        // Command level: also requires go
        depends_on: {
            tools: [{alternatives: ["go"]}]
        }
        implementations: [
            {
                script: "go build ./..."
                runtimes: [{name: "native"}]
                platforms: [{name: "linux"}, {name: "macos"}]
                // Implementation level: also requires make
                depends_on: {
                    tools: [{alternatives: ["make"]}]
                }
            }
        ]
    }
]

// Effective dependencies for "build": git + go + make

Runtime-Aware Validation

Dependencies declared at root, command, or implementation level are always validated against the host system, regardless of the selected runtime. This ensures host-side prerequisites (like a container engine) are checked before execution begins.

To validate dependencies inside the container environment, use depends_on inside a container runtime block:

{
    name: "build"
    implementations: [
        {
            script: "go build ./..."
            runtimes: [{
                name: "container"
                image: "golang:1.26"
                depends_on: {
                    // Checked INSIDE the container
                    tools: [{alternatives: ["go"]}]
                    filepaths: [{alternatives: ["/workspace/go.mod"]}]
                }
            }]
            platforms: [{name: "linux"}]
            // Host-level: always checked on the host
            depends_on: {
                tools: [{alternatives: ["docker", "podman"]}]
            }
        }
    ]
}

Container Runtime Dependencies

The depends_on block inside a container runtime config validates against the container's environment. This is only available for the container runtime — native and virtual runtimes do not support runtime-level depends_on.

Scope	Validated Against
Root / Command / Implementation depends_on	Always the host system
Container runtime depends_on	The container's environment

This separation lets you express both host and container requirements:

{
    name: "deploy"
    implementations: [{
        script: "./scripts/deploy.sh"
        runtimes: [{
            name: "container"
            image: "debian:stable-slim"
            depends_on: {
                // These are validated inside the container
                tools: [{alternatives: ["kubectl"]}]
                env_vars: [{alternatives: [{name: "KUBECONFIG"}]}]
            }
        }]
        platforms: [{name: "linux"}]
        // These are validated on the host (regardless of runtime)
        depends_on: {
            tools: [{alternatives: ["docker", "podman"]}]
            env_vars: [{alternatives: [{name: "DOCKER_HOST"}]}]
        }
    }]
}

Only the selected runtime's depends_on is validated. If a command has multiple runtimes listed, deps for unselected runtimes are skipped.

Error Messages

When dependencies aren't satisfied, Invowk shows a helpful error:

✗ Dependencies not satisfied

Command 'deploy' has unmet dependencies:

Missing Tools:
  • docker - not found in PATH
  • kubectl - not found in PATH

Missing Files:
  • Dockerfile - file not found

Missing Environment Variables:
  • AWS_ACCESS_KEY_ID - not set in environment

Install the missing tools and try again.

Complete Example

Here's a command with multiple dependency types:

{
    name: "deploy"
    description: "Deploy to production"
    depends_on: {
        // Check environment first
        env_vars: [
            {alternatives: [{name: "AWS_ACCESS_KEY_ID"}, {name: "AWS_PROFILE"}]}
        ]
        // Check required tools
        tools: [
            {alternatives: ["docker", "podman"]},
            {alternatives: ["kubectl"]}
        ]
        // Check required files
        filepaths: [
            {alternatives: ["Dockerfile"]},
            {alternatives: ["k8s/deployment.yaml"]}
        ]
        // Check network connectivity
        capabilities: [
            {alternatives: ["internet"]}
        ]
        // Run other commands first
        cmds: [
            {alternatives: ["build"]},
            {alternatives: ["test"]}
        ]
    }
    implementations: [
        {
            script: "./scripts/deploy.sh"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        }
    ]
}

Next Steps

Learn about each dependency type in detail:

• Tools - Check for binaries in PATH
• Filepaths - Check for files and directories
• Commands - Use cmds to require other commands to be discoverable
• Capabilities - Check system capabilities
• Environment Variables - Check environment variables
• Custom Checks - Write custom validation scripts