Configuration Schema Reference

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: ~/.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.