Version: 0.1.0-alpha.2

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 invkfiles and modules
#IncludeEntry: {
    path:   string  // Must end with .invkmod, /invkfile.cue, or /invkfile
    alias?: string  // Optional, only valid for .invkmod paths
}

// 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
    binary_path?: string
    modules_paths?: [...string]
    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.

search_paths

Type: [...string]
Required: No
Default: []

Additional directories to search for invkfiles and modules.

search_paths: [
    "~/.invowk/cmds",
    "~/projects/shared-commands",
    "/opt/company/invowk-commands",
]

Path resolution:

Paths starting with ~ are expanded to the user's home directory
Relative paths are resolved from the current working directory
Non-existent paths are silently ignored

Search priority (highest to lowest):

Current directory
Paths in search_paths (in order)
~/.invowk/cmds

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

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: {}

Configuration for the virtual shell runtime.

virtual_shell: {
    enable_uroot_utils: true
}

ui

Type: #UIConfig
Required: No
Default: {}

User interface configuration.

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

container

Type: #ContainerConfig
Required: No
Default: {}

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:

File operations: ls, cat, cp, mv, rm, mkdir, chmod
Text processing: grep, sed, awk, sort, uniq
And many more core utilities

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 --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: {}

Controls automatic provisioning of invowk resources into containers.

container: {
    auto_provision: {
        enabled: true
        binary_path: "/usr/local/bin/invowk"
        modules_paths: ["/opt/company/invowk-modules"]
        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
    binary_path?: string
    modules_paths?: [...string]
    cache_dir?:   string
}

enabled

Type: bool
Required: No
Default: true

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

binary_path

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

Overrides the path to the invowk binary to provision.

modules_paths

Type: [...string] Required: No Default: []

Additional module directories to provision into containers.

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 invkfiles and modules to include in discovery.
// Each entry specifies a path to an invkfile.cue, invkfile, or *.invkmod.
// Modules may have an optional alias for collision disambiguation.
includes: [
    // Personal commands
    {path: "~/.invowk/cmds/invkfile.cue"},

    // Team shared module (with alias)
    {path: "~/work/shared.invkmod", alias: "team"},

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

// 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 --invk-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.

Overview​

Schema Definition​

Config​

container_engine​

search_paths​

default_runtime​

virtual_shell​

ui​

container​

VirtualShellConfig​

enable_uroot_utils​

UIConfig​

color_scheme​

verbose​

interactive​

ContainerConfig​

auto_provision​

AutoProvisionConfig​

enabled​

binary_path​

modules_paths​

cache_dir​

Complete Example​

Minimal Configuration​

Validation​