Invowkfile Schema Reference

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

:::note 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.

:::caution 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.

:::warning 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

:::caution 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"]}]
        }
    },
]