Environment Overview

Invowk™ provides powerful environment variable management for your commands. Set variables, load from files, and control precedence across multiple levels.

Quick Example

{
    name: "build"
    env: {
        // Load from .env files
        files: [".env", ".env.local?"]  // ? means optional
        
        // Set variables directly
        vars: {
            NODE_ENV: "production"
            BUILD_DATE: "$(date +%Y-%m-%d)"
        }
    }
    implementations: [{
        script: """
            echo "Building for $NODE_ENV"
            echo "Date: $BUILD_DATE"
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Environment Sources

Variables come from multiple sources, in order of precedence (highest first):

1. CLI env vars - --env-var KEY=value
2. CLI env files - --env-file .env.custom
3. Invowk vars - INVOWK_FLAG_* / INVOWK_ARG_*
4. Implementation vars - Implementation-level env.vars
5. Command vars - Command-level env.vars
6. Root vars - Root-level env.vars
7. Implementation files - Implementation-level env.files
8. Command files - Command-level env.files
9. Root files - Root-level env.files
10. System environment - Host's environment variables (subject to env_inherit_mode)

Earlier sources override later ones.

Scope Levels

Root Level

Applies to all commands in the invkfile:

env: {
    vars: {
        PROJECT_NAME: "myproject"
    }
}

cmds: [...]  // All commands get PROJECT_NAME

Command Level

Applies to a specific command:

{
    name: "build"
    env: {
        vars: {
            BUILD_MODE: "release"
        }
    }
    implementations: [...]
}

Implementation Level

Applies to a specific implementation:

{
    name: "build"
    implementations: [
        {
            script: "npm run build"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
            env: {
                vars: {
                    NODE_ENV: "production"
                }
            }
        }
    ]
}

Platform Level

Set variables per platform:

// Platform-specific env requires separate implementations
implementations: [
    {
        script: "echo $CONFIG_PATH"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}]
        env: {vars: {CONFIG_PATH: "/etc/myapp/config"}}
    },
    {
        script: "echo $CONFIG_PATH"
        runtimes: [{name: "native"}]
        platforms: [{name: "macos"}]
        env: {vars: {CONFIG_PATH: "/usr/local/etc/myapp/config"}}
    }
]

Env Files

Load variables from .env files:

env: {
    files: [
        ".env",           // Required - fails if missing
        ".env.local?",    // Optional - suffix with ?
        ".env.${ENV}?",   // Interpolation - uses ENV variable
    ]
}

Files are loaded in order; later files override earlier ones.

See Env Files for details.

Environment Variables

Set variables directly:

env: {
    vars: {
        API_URL: "https://api.example.com"
        DEBUG: "true"
        VERSION: "1.0.0"
    }
}

See Env Vars for details.

CLI Overrides

Override at runtime:

# Set a single variable
invowk cmd build --invk-env-var NODE_ENV=development

# Set multiple variables
invowk cmd build --invk-env-var NODE_ENV=dev --invk-env-var DEBUG=true

# Load from a file
invowk cmd build --invk-env-file .env.local

# Combine
invowk cmd build --invk-env-file .env.local --invk-env-var OVERRIDE=value

Host Environment Inheritance

By default, native and virtual runtimes inherit the host environment, while container runtime starts with no host variables. You can control this per runtime or per invocation.

runtimes: [{
    name:              "container"
    image:             "alpine:latest"
    env_inherit_mode:  "allow"
    env_inherit_allow: ["TERM", "LANG"]
    env_inherit_deny:  ["AWS_SECRET_ACCESS_KEY"]
}]

invowk cmd examples hello \
  --invk-env-inherit-mode allow \
  --invk-env-inherit-allow TERM \
  --invk-env-inherit-allow LANG \
  --invk-env-inherit-deny AWS_SECRET_ACCESS_KEY

Built-in Variables

Invowk provides variables for flags and arguments:

• INVOWK_FLAG_* - Flag values
• INVOWK_ARG_* - Argument values

Container Environment

For container runtime, environment is passed into the container:

{
    name: "build"
    env: {
        vars: {
            BUILD_ENV: "container"
        }
    }
    implementations: [{
        script: "echo $BUILD_ENV"  // Available inside container
        runtimes: [{name: "container", image: "debian:bookworm-slim"}]
        platforms: [{name: "linux"}]
    }]
}

Nested Commands

When a command invokes another command, some variables are isolated:

Isolated (NOT inherited):

• INVOWK_ARG_*
• INVOWK_FLAG_*

Inherited (normal UNIX behavior):

• Variables from env.vars
• Platform-level variables
• System environment

This prevents parent command arguments from leaking into child commands.

Next Steps

• Env Files - Load from .env files
• Env Vars - Set variables directly
• Precedence - Understand override order