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: {content: """
            echo "Building for $NODE_ENV"
            echo "Date: $BUILD_DATE"
            """}
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Environment Sources

Variables come from multiple sources, applied in this order (lowest to highest precedence):

1. System environment - Host's environment variables (subject to env_inherit_mode)
2. Root files - Root-level env.files
3. Command files - Command-level env.files
4. Implementation files - Implementation-level env.files
5. Root vars - Root-level env.vars
6. Command vars - Command-level env.vars
7. Implementation vars - Implementation-level env.vars
8. Invowk vars - Built-in command vars (INVOWK_*, ARG*)
9. CLI env files - --ivk-env-file .env.custom
10. CLI env vars - --ivk-env-var KEY=value

Later sources override earlier ones.

Scope Levels

Root Level

Applies to all commands in the invowkfile:

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: {content: "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: {content: "echo $CONFIG_PATH"}
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}]
        env: {vars: {CONFIG_PATH: "/etc/myapp/config"}}
    },
    {
        script: {content: "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 --ivk-env-var NODE_ENV=development

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

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

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

Host Environment Inheritance

By default, native, virtual-sh, and virtual-lua 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:             "debian:stable-slim"
    env_inherit_mode:  "allow"
    env_inherit_allow: ["TERM", "LANG"]
    env_inherit_deny:  ["AWS_SECRET_ACCESS_KEY"]
}]
platforms: [{name: "linux"}]

invowk cmd examples hello 
  --ivk-env-inherit-mode allow 
  --ivk-env-inherit-allow TERM 
  --ivk-env-inherit-allow LANG 
  --ivk-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

Additionally, invowk injects metadata variables during command execution:

Variable	Description	Always Set
INVOWK_CMD_NAME	Current command name	Yes
INVOWK_RUNTIME	Resolved runtime name (native, virtual-sh, virtual-lua, container)	Yes
INVOWK_SOURCE	Source origin (invowkfile for root commands, module name for module commands)	Yes
INVOWK_PLATFORM	Resolved platform (linux, macos, windows)	Yes

Container Environment

For container runtime, environment is passed into the container:

{
    name: "build"
    env: {
        vars: {
            BUILD_ENV: "container"
        }
    }
    implementations: [{
        script: {content: "echo $BUILD_ENV"}  // Available inside container
        runtimes: [{name: "container", image: "debian:stable-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