Configuration Schema Reference

:::warning Alpha — Configuration Options May Change The configuration schema is still being refined. Options may be added, renamed, or removed between releases as we finalize the feature set. :::

Complete reference for the Invowk™ configuration file schema.

Overview

The configuration file uses CUE format and is located at:

Platform	Location
Linux	~/.config/invowk/config.cue
macOS	~/Library/Application Support/invowk/config.cue
Windows	%APPDATA%\invowk\config.cue

Configuration files are validated as closed structs, so unknown fields cause a validation error.

Schema Definition

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

// Include entry for modules
#IncludeEntry: {
    path:   string  // Must be absolute and end with .invowkmod
    alias?: string  // Optional, for collision disambiguation
}

// Virtual shell configuration
#VirtualShellConfig: {
    enable_uroot_utils?: bool
}

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

// Container configuration
#ContainerConfig: {
    auto_provision?: #AutoProvisionConfig
}

// Auto-provisioning configuration
#AutoProvisionConfig: {
    enabled?:          bool
    strict?:           bool
    binary_path?:      string
    includes?:         [...#IncludeEntry]
    inherit_includes?: bool
    cache_dir?:        string
}

Config

The root configuration object.

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

container_engine

Type: "podman" | "docker"
Required: No
Default: "podman"

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

container_engine: "podman"

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

includes

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

Additional modules to include in command discovery. Each entry specifies a path to an *.invowkmod directory with an optional alias for collision disambiguation.

includes: [
    {path: "/home/user/.invowk/modules/tools.invowkmod"},
    {path: "/home/user/projects/shared.invowkmod", alias: "shared"},
    {path: "/opt/company/tools.invowkmod"},
]

Path requirements:

• Paths must be absolute and end with .invowkmod
• Non-existent paths are silently ignored
• Duplicate paths are rejected

Alias rules:

• Aliases are optional, for collision disambiguation
• Each alias must be unique across all includes entries
• Aliases override the module's declared identifier for collision resolution

Discovery priority (highest to lowest):

1. Current directory invowkfile
2. Local modules (*.invowkmod in current directory)
3. Configured includes (in order) — explicit includes outrank the user directory
4. ~/.invowk/cmds (modules only, non-recursive)

default_runtime

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

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

default_runtime: "native"

Value	Description
"native"	Execute using the system's native shell
"virtual"	Execute using Invowk's built-in shell interpreter
"container"	Execute inside a container

virtual_shell

Type: #VirtualShellConfig
Required: No
Default: {enable_uroot_utils: true}

Configuration for the virtual shell runtime.

virtual_shell: {
    enable_uroot_utils: true
}

ui

Type: #UIConfig
Required: No
Default: {color_scheme: "auto", verbose: false, interactive: false}

User interface configuration.

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

container

Type: #ContainerConfig
Required: No
Default: {auto_provision: {enabled: true, strict: false, inherit_includes: true}}

Container runtime configuration.

container: {
    auto_provision: {
        enabled: true
    }
}

---

VirtualShellConfig

Configuration for the virtual shell runtime (mvdan/sh).

#VirtualShellConfig: {
    enable_uroot_utils?: bool
}

enable_uroot_utils

Type: bool
Required: No
Default: true

Enables u-root utilities in the virtual shell environment. When enabled, provides additional commands beyond basic shell builtins.

virtual_shell: {
    enable_uroot_utils: true
}

Available utilities when enabled (28 total):

• Upstream wrappers (12): base64, cat, cp, find, gzip, ls, mkdir, mv, rm, shasum, tar, touch
• Custom implementations (16): basename, cut, dirname, grep, head, ln, mktemp, realpath, seq, sleep, sort, tail, tee, tr, uniq, wc

---

UIConfig

User interface configuration.

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

color_scheme

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

Sets the color scheme for terminal output.

ui: {
    color_scheme: "auto"
}

Value	Description
"auto"	Detect from terminal (respects COLORTERM, TERM, etc.)
"dark"	Colors optimized for dark terminals
"light"	Colors optimized for light terminals

verbose

Type: bool
Required: No
Default: false

Enables verbose output by default for all commands.

ui: {
    verbose: true
}

Equivalent to always passing --ivk-verbose on the command line.

interactive

Type: bool
Required: No
Default: false

Enables interactive mode by default (alternate screen buffer with PTY).

ui: {
    interactive: true
}

---

ContainerConfig

Configuration for container runtime behavior.

#ContainerConfig: {
    auto_provision?: #AutoProvisionConfig
}

auto_provision

Type: #AutoProvisionConfig Required: No Default: {enabled: true, strict: false, inherit_includes: true}

Controls automatic provisioning of invowk resources into containers.

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

With auto-provisioning enabled, Invowk builds a cached, derived image by attaching a small provisioned layer on top of your base image. This runs for every container execution (interactive or not); if provisioning fails, Invowk warns and uses the base image.

---

AutoProvisionConfig

Auto-provisioning configuration for container images.

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

enabled

Type: bool Required: No Default: true

Enables auto-provisioning of the invowk binary and modules into containers.

strict

Type: bool Required: No Default: false

Makes provisioning failure a hard error instead of falling back to the unprovisioned base image. When false (the default), provisioning failure logs a warning and continues with the base image.

binary_path

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

Overrides the path to the invowk binary to provision.

includes

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

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

inherit_includes

Type: bool Required: No 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.

cache_dir

Type: string
Required: No
Default: (empty — uses platform-specific default, typically ~/.cache/invowk/provision)

Overrides the cache directory for provisioned image metadata.

---

Complete Example

A fully documented configuration file:

// Invowk Configuration File
// =========================
// Location: ~/.config/invowk/config.cue

// Container Engine
// ----------------
// Which container runtime to use: "podman" or "docker"
container_engine: "podman"

// Includes
// --------
// Additional modules to include in discovery.
// Each entry specifies a path to an *.invowkmod directory.
// Modules may have an optional alias for collision disambiguation.
includes: [
    // Personal modules
    {path: "/home/user/.invowk/modules/tools.invowkmod"},

    // Team shared module (with alias)
    {path: "/home/user/work/shared.invowkmod", alias: "team"},

    // Organization-wide module
    {path: "/opt/company/tools.invowkmod"},
]

// Default Runtime
// ---------------
// The runtime to use when a command doesn't specify one
// Options: "native", "virtual", "container"
default_runtime: "native"

// Virtual Shell Configuration
// ---------------------------
// Settings for the virtual shell runtime (mvdan/sh)
virtual_shell: {
    // Enable u-root utilities for more shell commands
    // Provides ls, cat, grep, etc. in the virtual environment
    enable_uroot_utils: true
}

// UI Configuration
// ----------------
// User interface settings
ui: {
    // Color scheme: "auto", "dark", or "light"
    // "auto" detects from terminal settings
    color_scheme: "auto"
    
    // Enable verbose output by default
    // Same as always passing --ivk-verbose
    verbose: false

    // Enable interactive mode by default
    interactive: false
}

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

---

Minimal Configuration

If you're happy with defaults, a minimal config might be:

// Just override what you need
container_engine: "docker"

Or even an empty file (all defaults):

// Empty config - use all defaults

---

Validation

You can validate your configuration file using CUE:

cue vet ~/.config/invowk/config.cue

Or check it with Invowk:

invowk config show

If there are any errors, Invowk will report them when loading the configuration.