Skip to main content
Version: 0.1.0

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.

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 (short f), force-rebuild, version
  • The ivk-, invowk-, and i- prefixes are also reserved for system flags

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