Invkfile Schema Reference

Alpha — Schema May Change

The invkfile 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 invkfile schema. Invkfiles use CUE format for defining commands. Invkfiles are validated as closed structs, so unknown fields cause a validation error.

Root Structure

Every invkfile must define at least one command in cmds:

#Invkfile: {
    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 invkmod.cue

Fields like module, version, description, and requires belong in invkmod.cue and are rejected in invkfile.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: Invkfile directory

Default working directory for all commands. Can be absolute or relative to the invkfile 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 invkfile. See Command.

---

Command

Defines an executable command:

#Command: {
    name:            string               // Required
    description?:    string               // Optional
    implementations: [...#Implementation] // Required - at least one
    env?:            #EnvConfig           // Optional
    workdir?:        string               // Optional
    depends_on?:     #DependsOn           // Optional
    flags?:          [...#Flag]           // Optional
    args?:           [...#Argument]       // Optional
}

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.

description: "Build the application for production"

implementations

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

The executable implementations. See Implementation.

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:

• env-file (short e), env-var (short E)
• env-inherit-mode, env-inherit-allow, env-inherit-deny
• workdir (short w), help (short h), runtime (short r)
• from, force-rebuild, list (short l)

args

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

Positional arguments for this command. See Argument.

---

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
}

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

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

// Container with options
runtimes: [{
    name: "container"
    image: "golang:1.22"
    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"},
]

---

RuntimeConfig

Configuration for a specific runtime:

#RuntimeConfig: {
    name: "native" | "virtual" | "container"
    
    // Host environment inheritance:
    env_inherit_mode?:  "none" | "allow" | "all"
    env_inherit_allow?: [...string]
    env_inherit_deny?:  [...string]

    // For native and container:
    interpreter?: string
    
    // For container only:
    enable_host_ssh?: bool
    containerfile?:   string
    image?:           string
    volumes?:         [...string]
    ports?:           [...string]
}

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: [{
    name:              "container"
    image:             "alpine:latest"
    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: [{
    name: "container"
    image: "debian:bookworm-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:bookworm-slim"
image: "golang:1.22"

// 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",
]

---

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

#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
}

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)
}

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.

---

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