Version: 0.1.0-alpha.3

Invkfile Schema Reference

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

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

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

Root Structure​

default_shell​

workdir​

env​

depends_on​

cmds​

Command​

name​

description​

implementations​

flags​

args​

Implementation​

script​

runtimes​

platforms​

RuntimeConfig​

name​

interpreter​

env_inherit_mode​

env_inherit_allow​

env_inherit_deny​

enable_host_ssh​

containerfile / image​

volumes​

ports​

PlatformConfig​

EnvConfig​

files​

vars​

DependsOn​

ToolDependency​

CommandDependency​

FilepathDependency​

CapabilityDependency​

EnvVarDependency​

CustomCheckDependency​

Flag​

Argument​

Complete Example​

Root Structure

default_shell

workdir

env

depends_on

cmds

Command

name

description

implementations

flags

args

Implementation

script

runtimes

platforms

RuntimeConfig

name

interpreter

env_inherit_mode

env_inherit_allow

env_inherit_deny

enable_host_ssh

containerfile / image

volumes

ports

PlatformConfig

EnvConfig

files

vars

DependsOn

ToolDependency

CommandDependency

FilepathDependency

CapabilityDependency

EnvVarDependency

CustomCheckDependency

Flag

Argument

Complete Example