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, 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: "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 --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 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: [{
    platforms: [{name: "linux"}, {name: "macos"}]
    name:              "container"
    image:             "debian:stable-slim"
    env_inherit_mode:  "allow"
    env_inherit_allow: ["TERM", "LANG"]
    env_inherit_deny:  ["AWS_SECRET_ACCESS_KEY"]
}]

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, 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: "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