Configuration Options

This page documents all available configuration options for Invowk™.

Configuration Schema

The configuration file uses CUE format and follows this schema:

#Config: {
    container_engine?: "podman" | "docker"
    includes?: [...#IncludeEntry]
    default_runtime?: "native" | "virtual" | "container"
    virtual_shell?: #VirtualShellConfig
    ui?: #UIConfig
    container?: #ContainerConfig
}

#IncludeEntry: {
    path:   string  // Must end with .invkmod
    alias?: string  // Optional, for collision disambiguation
}

#VirtualShellConfig: {
    enable_uroot_utils?: bool
}

#UIConfig: {
    color_scheme?: "auto" | "dark" | "light"
    verbose?: bool
    interactive?: bool
}

#ContainerConfig: {
    auto_provision?: #AutoProvisionConfig
}

#AutoProvisionConfig: {
    enabled?: bool
    binary_path?: string
    includes?: [...#IncludeEntry]
    inherit_includes?: bool
    cache_dir?: string
}

Unknown fields are rejected, so keep config files limited to the schema-defined options.

Options Reference

container_engine

Type: "podman" | "docker"
Default: "podman"

Specifies which container runtime to use for container-based command execution.

container_engine: "docker"  // or "podman"

If the preferred engine is not available, Invowk falls back to the other engine when container runtime is needed.

includes

Type: [...#IncludeEntry] Default: []

Additional modules to include in command discovery. Each entry is an #IncludeEntry with a required path (must end with .invkmod) and optional alias.

includes: [
    {path: "~/.invowk/modules/tools.invkmod"},
    {path: "~/my-company/shared.invkmod", alias: "company"},
]

Path requirements:

• Must end with .invkmod
• Duplicate paths are rejected

Alias rules:

• Optional, for collision disambiguation
• Must be unique across all includes entries

Discovery Order:

1. Current directory invkfile (always searched first, highest priority)
2. Local modules (*.invkmod in current directory)
3. ~/.invowk/cmds (always included)
4. Each entry in includes in order

Commands from earlier entries override commands with the same name from later entries.

default_runtime

Type: "native" | "virtual" | "container"
Default: "native"

Sets the global default runtime mode for commands that don't specify a runtime.

default_runtime: "virtual"

Runtime Options:

• "native" - Execute using the system's native shell (bash, zsh, PowerShell, etc.)
• "virtual" - Execute using Invowk's built-in shell interpreter (mvdan/sh)
• "container" - Execute inside a container (requires Docker or Podman)

note

Commands can override this default by specifying their own runtime in the implementations field.

virtual_shell

Type: #VirtualShellConfig
Default: {}

Configures the virtual shell runtime behavior.

virtual_shell: {
    enable_uroot_utils: true
}

virtual_shell.enable_uroot_utils

Type: bool Default: true

Enables u-root utilities in the virtual shell. When enabled, 15 additional POSIX-compliant commands become available:

File Operations: cat, cp, ls, mkdir, mv, rm, touch

Text Processing: head, tail, wc, grep, sort, uniq, cut, tr

virtual_shell: {
    enable_uroot_utils: true
}

This makes the virtual shell self-contained, allowing scripts to execute common file and text operations without requiring external binaries on the host system.

tip

u-root utilities are enabled by default. Set to false only if you need to force scripts to use system binaries or reduce binary size.

ui

Type: #UIConfig
Default: {}

Configures the user interface settings.

ui: {
    color_scheme: "dark"
    verbose: false
    interactive: false
}

ui.color_scheme

Type: "auto" | "dark" | "light"
Default: "auto"

Sets the color scheme for Invowk's output.

ui: {
    color_scheme: "auto"
}

Options:

• "auto" - Detect from terminal settings (respects COLORTERM, TERM, etc.)
• "dark" - Use colors optimized for dark terminals
• "light" - Use colors optimized for light terminals

ui.verbose

Type: bool
Default: false

Enables verbose output by default. When enabled, Invowk prints additional information about command discovery, dependency validation, and execution.

ui: {
    verbose: true
}

This is equivalent to always passing --invk-verbose on the command line.

ui.interactive

Type: bool
Default: false

Enables interactive mode by default. When enabled, commands run in an alternate screen buffer with full PTY support, allowing interactive programs like password prompts, confirmations, and other stdin-based interactions to work properly.

ui: {
    interactive: true
}

This is equivalent to always passing --invk-interactive on the command line.

container

Type: #ContainerConfig
Default: {}

Configures container runtime behavior.

container: {
    auto_provision: {
        enabled: true
        binary_path: "/usr/local/bin/invowk"
        includes: [
            {path: "/opt/company/modules/tools.invkmod"},
        ]
        inherit_includes: true
        cache_dir: "/tmp/invowk/provision"
    }
}

container.auto_provision.enabled

Type: bool
Default: true

Enables automatic provisioning of the invowk binary and modules into container images. When enabled, Invowk builds a cached, derived image for every container run by attaching a small provisioned layer on top of your base image. If provisioning fails, Invowk warns and uses the base image.

container.auto_provision.binary_path

Type: string
Default: (empty; uses the running invowk binary)

Overrides the path to the invowk binary to provision into containers.

container.auto_provision.includes

Type: [...#IncludeEntry] Default: []

Additional modules to provision into containers. Uses the same #IncludeEntry format as root includes (each entry has a path ending with .invkmod and an optional alias).

container.auto_provision.inherit_includes

Type: bool Default: true

When true, the root-level includes entries are automatically inherited by auto-provisioning. Set to false to provision only the modules explicitly listed in container.auto_provision.includes.

container.auto_provision.cache_dir

Type: string
Default: ~/.cache/invowk/provision

Overrides the cache directory for provisioned image metadata.

Complete Example

Here's a complete configuration file with all options:

// Invowk Configuration File
// Located at: ~/.config/invowk/config.cue

// Use Podman as the container engine
container_engine: "podman"

// Additional modules to include in discovery
includes: [
    {path: "~/.invowk/modules/tools.invkmod"},       // Personal modules
    {path: "~/work/shared.invkmod", alias: "team"},   // Team shared module
]

// Default to virtual shell for portability
default_runtime: "virtual"

// Virtual shell settings
virtual_shell: {
    // Enable u-root utilities for more shell commands
    enable_uroot_utils: true
}

// UI preferences
ui: {
    // Auto-detect color scheme from terminal
    color_scheme: "auto"
    
    // Don't be verbose by default
    verbose: false
    
    // Enable interactive mode for commands with stdin (e.g., password prompts)
    interactive: false
}

// Container provisioning
container: {
    auto_provision: {
        enabled: true
    }
}