Invowkfile Schema Reference

Alpha — Schema May Change

The invowkfile schema is still evolving. Fields, types, and validation rules may change between releases as we stabilize the format. Always check the changelog when upgrading.

Complete reference for the invowkfile schema. Invowkfiles use CUE format for defining commands. Invowkfiles are validated as closed structs, so unknown fields cause a validation error.

Root Structure

Every invowkfile must define at least one command in cmds:

#Invowkfile: {
    default_shell?: string    // Optional - override default shell
    workdir?:       string    // Optional - default working directory
    env?:           #EnvConfig      // Optional - global environment
    depends_on?:    #DependsOn      // Optional - global dependencies
    cmds:           [...#Command]   // Required - at least one command
}

Module Metadata Lives in invowkmod.cue

Fields like module, version, description, and requires belong in invowkmod.cue and are rejected in invowkfile.cue.

default_shell

Type: string
Required: No
Default: System default

Override the default shell for native runtime execution.

default_shell: "/bin/bash"
default_shell: "pwsh"

workdir

Type: string
Required: No
Default: Invowkfile directory

Default working directory for all commands. Can be absolute or relative to the invowkfile location.

workdir: "./src"
workdir: "/opt/app"

env

Type: #EnvConfig
Required: No

Global environment configuration applied to all commands. See EnvConfig.

depends_on

Type: #DependsOn
Required: No

Global dependencies that apply to all commands. See DependsOn.

cmds

Type: [...#Command] Required: Yes (at least one)

List of commands defined in this invowkfile. See Command.

Migration Note

The field name is cmds, not commands. Using commands will cause a CUE validation error because the schema defines commands?: _|_ (bottom value) to enforce the correct name.

---

Command

Defines an executable command:

#Command: {
    name:            string               // Required
    description?:    string               // Optional
    category?:       string               // Optional - groups in listing
    implementations: [...#Implementation] // Required - at least one
    env?:            #EnvConfig           // Optional
    workdir?:        string               // Optional
    depends_on?:     #DependsOn           // Optional
    flags?:          [...#Flag]           // Optional
    args?:           [...#Argument]       // Optional
    watch?:          #WatchConfig         // Optional - file-watching
}

name

Type: string (pattern: ^[a-zA-Z][a-zA-Z0-9_ -]*$)
Required: Yes

The command identifier. Must start with a letter.

name: "build"
name: "test unit"     // Spaces allowed for subcommand-like behavior
name: "deploy-prod"

description

Type: string Required: No

Help text for the command. When provided, it must be non-empty (validated by regex pattern ^\s*\S.*$ -- whitespace-only strings are rejected).

description: "Build the application for production"

category

Type: string Required: No

Groups this command under a heading in invowk cmd listing output. When provided, it must be non-empty (validated by regex pattern ^\s*\S.*$ — whitespace-only strings are rejected).

cmds: [
    {
        name: "build"
        category: "Development"
        implementations: [...]
    },
    {
        name: "test unit"
        category: "Development"
        implementations: [...]
    },
    {
        name: "deploy"
        category: "Operations"
        implementations: [...]
    },
]

implementations

Type: [...#Implementation] Required: Yes (at least one)

The executable implementations. See Implementation.

env

Type: #EnvConfig Required: No

Environment configuration for this command. Command-level env is applied before implementation-level env. See EnvConfig.

workdir

Type: string Required: No

Working directory for command execution. Overrides root-level workdir but can be overridden by implementation-level workdir. Can be absolute or relative to the invowkfile location.

depends_on

Type: #DependsOn Required: No

Dependencies that must be satisfied before running this command. See DependsOn.

flags

Type: [...#Flag]
Required: No

Command-line flags for this command. See Flag.

Reserved Flags

The following flags are reserved by invowk and cannot be used in user-defined commands:

• ivk-env-file (-e), ivk-env-var (-E)
• ivk-env-inherit-mode, ivk-env-inherit-allow, ivk-env-inherit-deny
• ivk-workdir (-w), ivk-runtime (-r), ivk-from (-f)
• ivk-force-rebuild, ivk-dry-run
• ivk-watch (-W)
• ivk-verbose (-v), ivk-config (-c), ivk-interactive (-i)
• help (-h), version

Additionally, any flag starting with the ivk-, invowk-, or i- prefix is reserved for system flags.

args

Type: [...#Argument]
Required: No

Positional arguments for this command. See Argument.

watch

Type: #WatchConfig Required: No

File-watching configuration for this command. When defined, patterns controls which files are watched. When --ivk-watch is passed without a watch config, invowk falls back to watching all files (**/*) in the working directory. See WatchConfig.

{
    name: "dev"
    description: "Run development server with auto-reload"
    watch: {
        patterns: ["src/**/*.go", "*.go"]
        debounce: "1s"
        clear_screen: true
        ignore: ["vendor/**"]
    }
    implementations: [{
        script: "go run ./cmd/server"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

---

Implementation

Defines how a command is executed:

#Implementation: {
    script:      string       // Required - inline script or file path
    runtimes:    [...#RuntimeConfig] & [_, ...]  // Required - runtime configurations
    platforms:   [...#PlatformConfig] & [_, ...]  // Required - at least one platform
    env?:        #EnvConfig   // Optional
    workdir?:    string       // Optional
    depends_on?: #DependsOn   // Optional
    timeout?:    #DurationString  // Optional - max execution time
}

script

Type: string (non-empty)
Required: Yes

The shell commands to execute OR a path to a script file.

// Inline script
script: "echo 'Hello, World!'"

// Multi-line script
script: """
    echo "Building..."
    go build -o app .
    echo "Done!"
    """

// Script file reference
script: "./scripts/build.sh"
script: "deploy.py"

Recognized extensions: .sh, .bash, .ps1, .bat, .cmd, .py, .rb, .pl, .zsh, .fish

runtimes

Type: [...#RuntimeConfig]
Required: Yes (at least one)

The runtimes that can execute this implementation. The first runtime is the default.

// Native only
runtimes: [{name: "native"}]
platforms: [{name: "linux"}, {name: "macos"}]

// Multiple runtimes
runtimes: [
platforms: [{name: "linux"}, {name: "macos"}]
    {name: "native"},
    {name: "virtual"},
]

// Container with options
runtimes: [{
platforms: [{name: "linux"}, {name: "macos"}]
    name: "container"
    image: "golang:1.26"
    volumes: ["./:/app"]
}]

platforms

Type: [...#PlatformConfig] Required: Yes (at least one)

Specify which operating systems this implementation supports.

// Linux and macOS only
platforms: [
    {name: "linux"},
    {name: "macos"},
]

env

Type: #EnvConfig Required: No

Environment configuration for this implementation. Merged with command-level env: implementation files are loaded after command-level files, and implementation vars override command-level vars. See EnvConfig.

workdir

Type: string Required: No

Working directory for this implementation. Overrides both root-level and command-level workdir settings. Can be absolute or relative to the invowkfile location.

depends_on

Type: #DependsOn Required: No

Dependencies that must be satisfied before running this implementation. Combined with root-level and command-level depends_on. Always validated against the host system, regardless of the selected runtime. To validate dependencies inside the runtime's environment (e.g., inside a container), use depends_on inside the runtime block instead. See DependsOn.

timeout

Type: #DurationString Required: No

Maximum execution duration. Must be a valid Go duration string (e.g., "30s", "5m", "1h30m"). When exceeded, the command is cancelled and returns a timeout error. The timeout value is validated early (before dependency checks) to fail fast on invalid values. See DurationString.

{
    name: "build"
    implementations: [{
        script: "make build"
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
        timeout: "5m"
    }]
}

---

RuntimeConfig

Configuration for a specific runtime:

// Shared base fields (all runtimes)
#RuntimeConfigBase: {
    name:               #RuntimeType
    env_inherit_mode?:  "none" | "allow" | "all"
    env_inherit_allow?: [...string]
    env_inherit_deny?:  [...string]
}

// Native runtime: supports interpreter
#RuntimeConfigNative: close({
    #RuntimeConfigBase
    name:         "native"
    interpreter?: string  // "auto", "python3", "/usr/bin/env perl -w", etc.
})

// Virtual runtime: no additional fields
#RuntimeConfigVirtual: close({
    #RuntimeConfigBase
    name: "virtual"
    // NOTE: interpreter is NOT allowed here (CUE validation error)
})

// Container runtime: image/containerfile + extras
#RuntimeConfigContainer: close({
    #RuntimeConfigBase
    name:              "container"
    interpreter?:      string
    enable_host_ssh?:  bool
    containerfile?:    string  // mutually exclusive with image
    image?:            string  // mutually exclusive with containerfile
    volumes?:          [...string]
    ports?:            [...string]
    depends_on?:       #DependsOn  // validated inside the container environment
})

// Discriminated union of all runtime types
#RuntimeConfig: #RuntimeConfigNative | #RuntimeConfigVirtual | #RuntimeConfigContainer

name

Type: "native" | "virtual" | "container"
Required: Yes

The runtime type.

interpreter

Type: string
Available for: native, container
Default: "auto" (detect from shebang)

Specifies how to execute the script.

// Auto-detect from shebang
interpreter: "auto"

// Specific interpreter
interpreter: "python3"
interpreter: "node"
interpreter: "/usr/bin/ruby"

// With arguments
interpreter: "python3 -u"
interpreter: "/usr/bin/env perl -w"

note

Virtual runtime uses mvdan/sh which cannot execute non-shell interpreters.

env_inherit_mode

Type: "none" | "allow" | "all"
Available for: native, virtual, container
Default: all for native/virtual, none for container

Controls whether the host environment is inherited by the runtime.

env_inherit_allow

Type: [...string]
Available for: native, virtual, container

Allowlist of host env vars when env_inherit_mode is "allow".

env_inherit_deny

Type: [...string]
Available for: native, virtual, container

Denylist of host env vars (applies to any mode).

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"]
}]

enable_host_ssh

Type: bool
Available for: container
Default: false

Enable SSH access from container back to the host. When enabled, Invowk starts an SSH server and provides credentials via environment variables:

• INVOWK_SSH_ENABLED
• INVOWK_SSH_HOST
• INVOWK_SSH_PORT
• INVOWK_SSH_USER
• INVOWK_SSH_TOKEN

runtimes: [{
    platforms: [{name: "linux"}, {name: "macos"}]
    name: "container"
    image: "debian:stable-slim"
    enable_host_ssh: true
}]

containerfile / image

Type: string
Available for: container

Specify the container source. These are mutually exclusive.

// Use a pre-built image
image: "debian:stable-slim"
image: "golang:1.26"

// Build from a Containerfile
containerfile: "./Containerfile"
containerfile: "./docker/Dockerfile.build"

volumes

Type: [...string]
Available for: container

Volume mounts in host:container[:options] format.

volumes: [
    "./src:/app/src",
    "/tmp:/tmp:ro",
    "${HOME}/.cache:/cache",
]

ports

Type: [...string] Available for: container

Port mappings in host:container format.

ports: [
    "8080:80",
    "3000:3000",
]

depends_on

Type: #DependsOn Available for: container Required: No

Dependencies validated inside the container environment. Unlike root/command/implementation-level depends_on (which always check the host), container runtime-level depends_on validates against the container's own environment — useful for verifying that the container image has the required tools, files, and configuration.

Only checked when the container runtime is selected at execution time.

---

PlatformConfig

#PlatformConfig: {
    name: "linux" | "macos" | "windows"
}

---

EnvConfig

Environment configuration:

#EnvConfig: {
    files?: [...string]         // Dotenv files to load
    vars?:  [string]: string    // Environment variables
}

files

Dotenv files to load. Files are loaded in order; later files override earlier ones.

env: {
    files: [
        ".env",
        ".env.local",
        ".env.${ENVIRONMENT}?",  // '?' means optional
    ]
}

vars

Environment variables as key-value pairs.

env: {
    vars: {
        NODE_ENV: "production"
        DEBUG: "false"
    }
}

---

DependsOn

Dependency specification:

#DependsOn: {
    tools?:         [...#ToolDependency]
    cmds?:          [...#CommandDependency]
    filepaths?:     [...#FilepathDependency]
    capabilities?:  [...#CapabilityDependency]
    custom_checks?: [...#CustomCheckDependency]
    env_vars?:      [...#EnvVarDependency]
}

ToolDependency

#ToolDependency: {
    alternatives: [...string]  // At least one - tool names
}

depends_on: {
    tools: [
        {alternatives: ["go"]},
        {alternatives: ["podman", "docker"]},  // Either works
    ]
}

CommandDependency

Field Name

The field name for command dependencies is cmds, not commands. Using commands will cause a CUE validation error because the schema defines commands?: _|_ (bottom value) to enforce the correct field name.

#CommandDependency: {
    alternatives: [...string]  // Command names
}

FilepathDependency

#FilepathDependency: {
    alternatives: [...string]  // File/directory paths
    readable?:    bool
    writable?:    bool
    executable?:  bool
}

CapabilityDependency

#CapabilityDependency: {
    alternatives: [...("local-area-network" | "internet" | "containers" | "tty")]
}

EnvVarDependency

#EnvVarDependency: {
    alternatives: [...#EnvVarCheck]
}

#EnvVarCheck: {
    name:        string    // Environment variable name
    validation?: string    // Regex pattern
}

CustomCheckDependency

#CustomCheckDependency: #CustomCheck | #CustomCheckAlternatives

#CustomCheck: {
    name:             string  // Check identifier
    check_script:     string  // Script to run
    expected_code?:   int     // Expected exit code (default: 0)
    expected_output?: string  // Regex to match output
}

#CustomCheckAlternatives: {
    alternatives: [...#CustomCheck]
}

---

Flag

Command-line flag definition:

#Flag: {
    name:          string    // POSIX-compliant name
    description:   string    // Help text
    default_value?: string   // Default value
    type?:         "string" | "bool" | "int" | "float"
    required?:     bool
    short?:        string    // Single character alias
    validation?:   string    // Regex pattern
}

Property	Required	Description
name	Yes	Flag name (alphanumeric, hyphens, underscores)
description	Yes	Help text (must be non-empty)
type	No	string, bool, int, float (default: string)
default_value	No	Default if not provided (cannot combine with required)
required	No	Must be provided (cannot combine with default_value)
short	No	Single-letter alias (a-z or A-Z)
validation	No	Regex pattern for value validation

flags: [
    {
        name: "output"
        short: "o"
        description: "Output file path"
        default_value: "./build"
    },
    {
        name: "verbose"
        short: "v"
        description: "Enable verbose output"
        type: "bool"
    },
]

---

Argument

Positional argument definition:

#Argument: {
    name:          string    // POSIX-compliant name
    description:   string    // Help text
    required?:     bool      // Must be provided
    default_value?: string   // Default if not provided
    type?:         "string" | "int" | "float"
    validation?:   string    // Regex pattern
    variadic?:     bool      // Accepts multiple values (last arg only)
}

Property	Required	Description
name	Yes	Argument name (alphanumeric, hyphens, underscores)
description	Yes	Help text (must be non-empty)
type	No	string, int, float (default: string; bool not supported)
default_value	No	Default if not provided (cannot combine with required)
required	No	Must be provided (cannot combine with default_value)
variadic	No	Accept multiple values (only allowed on the last argument)
validation	No	Regex pattern for value validation

args: [
    {
        name: "target"
        description: "Build target"
        required: true
    },
    {
        name: "files"
        description: "Files to process"
        variadic: true
    },
]

Environment Variables for Arguments:

• INVOWK_ARG_<NAME> - The argument value
• For variadic: INVOWK_ARG_<NAME>_COUNT, INVOWK_ARG_<NAME>_1, INVOWK_ARG_<NAME>_2, etc.

---

WatchConfig

File-watching configuration for automatic command re-execution:

#WatchConfig: {
    patterns:      [...string] & [_, ...] // Required - glob patterns to watch
    debounce?:     #DurationString        // Optional - default "500ms"
    clear_screen?: bool                   // Optional - default false
    ignore?:       [...string]            // Optional - merged with built-in defaults
}

patterns

Type: [...string] (at least one) Required: Yes

Glob patterns for files to watch. Patterns support ** for recursive matching (e.g., "src/**/*.go", "*.ts"). Paths are relative to the effective working directory of the command.

debounce

Type: #DurationString Required: No Default: "500ms"

Delay before re-executing after a file change is detected. See DurationString.

clear_screen

Type: bool Required: No Default: false

When true, clears the terminal before each re-execution.

ignore

Type: [...string] Required: No

Additional glob patterns for files/directories to exclude from watching. These are merged with built-in defaults (.git/**, node_modules/**, __pycache__/**, *.swp, etc.).

---

DurationString

// #DurationString — shared by timeout and debounce
// Valid examples: "500ms", "30s", "5m", "1h30m", "2.5s"
#DurationString: string & =~"^([0-9]+(\\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$"

Shared type used by #Implementation.timeout and #WatchConfig.debounce. Valid examples: "500ms", "30s", "5m", "1h30m", "2.5s".

---

Complete Example

env: {
    files: [".env"]
    vars: {
        APP_NAME: "myapp"
    }
}

cmds: [
    {
        name: "build"
        description: "Build the application"
        
        flags: [
            {
                name: "release"
                short: "r"
                description: "Build for release"
                type: "bool"
            },
        ]
        
        implementations: [
            {
                script: """
                    if [ "$INVOWK_FLAG_RELEASE" = "true" ]; then
                        go build -ldflags="-s -w" -o app .
                    else
                        go build -o app .
                    fi
                    """
                runtimes: [{name: "native"}]
                platforms: [{name: "linux"}, {name: "macos"}]
            },
            {
                script: """
                    $flags = if ($env:INVOWK_FLAG_RELEASE -eq "true") { "-ldflags=-s -w" } else { "" }
                    go build $flags -o app.exe .
                    """
                runtimes: [{name: "native", interpreter: "pwsh"}]
                platforms: [{name: "windows"}]
            },
        ]
        
        depends_on: {
            tools: [{alternatives: ["go"]}]
        }
    },
]