Skip to main content
Version: 0.1.0-alpha.2

Platform-Specific Commands

Create commands that behave differently on Linux, macOS, and Windows. Invowk™ automatically selects the right implementation for the current platform.

Supported Platforms​

ValueDescription
linuxLinux distributions
macosmacOS (Darwin)
windowsWindows

Basic Platform Targeting​

Restrict an implementation to specific platforms:

{
    name: "open-browser"
    implementations: [
        {
            script: "xdg-open http://localhost:3000"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}]
        },
        {
            script: "open http://localhost:3000"
            runtimes: [{name: "native"}]
            platforms: [{name: "macos"}]
        },
        {
            script: "start http://localhost:3000"
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
        }
    ]
}

Targeting All Platforms​

To target all platforms, list them explicitly:

{
    name: "build"
    implementations: [{
        script: "go build ./..."
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
    }]
}

Unix-Only Commands​

Target both Linux and macOS:

{
    name: "check-permissions"
    implementations: [{
        script: """
            chmod +x ./scripts/*.sh
            ls -la ./scripts/
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Platform-Specific Environment​

Set different environment variables per platform:

{
    name: "configure"
    implementations: [
        // Linux implementation
        {
            script: "echo \"Config: $CONFIG_PATH\""
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}]
            env: {
                vars: {
                    CONFIG_PATH: "/etc/myapp/config.yaml"
                    CACHE_DIR: "/var/cache/myapp"
                }
            }
        },
        // macOS implementation
        {
            script: "echo \"Config: $CONFIG_PATH\""
            runtimes: [{name: "native"}]
            platforms: [{name: "macos"}]
            env: {
                vars: {
                    CONFIG_PATH: "/usr/local/etc/myapp/config.yaml"
                    CACHE_DIR: "${HOME}/Library/Caches/myapp"
                }
            }
        },
        // Windows implementation
        {
            script: "echo \"Config: %CONFIG_PATH%\""
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
            env: {
                vars: {
                    CONFIG_PATH: "%APPDATA%\\myapp\\config.yaml"
                    CACHE_DIR: "%LOCALAPPDATA%\\myapp\\cache"
                }
            }
        }
    ]
}

Cross-Platform Scripts​

Write one script that works everywhere:

{
    name: "build"
    implementations: [
        // Unix platforms (same output name)
        {
            script: "go build -o bin/app ./..."
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}, {name: "macos"}]
        },
        // Windows (different output name)
        {
            script: "go build -o bin/app.exe ./..."
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
        }
    ]
}

CUE Templates for Platforms​

Use CUE templates to reduce repetition:

// Define platform templates
_linux: {name: "linux"}
_macos: {name: "macos"}
_windows: {name: "windows"}

_unix: [{name: "linux"}, {name: "macos"}]
_all: [{name: "linux"}, {name: "macos"}, {name: "windows"}]

cmds: [
    {
        name: "clean"
        implementations: [
            // Unix implementation
            {
                script: "rm -rf build/"
                runtimes: [{name: "native"}]
                platforms: _unix
            },
            // Windows implementation
            {
                script: "rmdir /s /q build"
                runtimes: [{name: "native"}]
                platforms: [_windows]
            }
        ]
    }
]

Command Listing​

The command list shows supported platforms:

Available Commands
  (* = default runtime)

From current directory:
  build - Build the project [native*] (linux, macos, windows)
  clean - Clean artifacts [native*] (linux, macos)
  deploy - Deploy to cloud [native*] (linux)

Unsupported Platform Error​

Running a command on an unsupported platform shows a clear error:

✗ Host not supported

Command 'deploy' cannot run on this host.

Current host:     windows
Supported hosts:  linux, macos

This command is only available on the platforms listed above.

Real-World Examples​

System Information​

{
    name: "sysinfo"
    implementations: [
        {
            script: """
                echo "Hostname: $(hostname)"
                echo "Kernel: $(uname -r)"
                echo "Memory: $(free -h | awk '/^Mem:/{print $2}')"
                """
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}]
        },
        {
            script: """
                echo "Hostname: $(hostname)"
                echo "Kernel: $(uname -r)"
                echo "Memory: $(sysctl -n hw.memsize | awk '{print $0/1024/1024/1024 "GB"}')"
                """
            runtimes: [{name: "native"}]
            platforms: [{name: "macos"}]
        },
        {
            script: """
                echo Hostname: %COMPUTERNAME%
                systeminfo | findstr "Total Physical Memory"
                """
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
        }
    ]
}

Package Installation​

{
    name: "install-deps"
    implementations: [
        {
            script: "apt-get install -y build-essential"
            runtimes: [{name: "native"}]
            platforms: [{name: "linux"}]
        },
        {
            script: "brew install coreutils"
            runtimes: [{name: "native"}]
            platforms: [{name: "macos"}]
        },
        {
            script: "choco install make"
            runtimes: [{name: "native"}]
            platforms: [{name: "windows"}]
        }
    ]
}

Best Practices​

  1. Start with cross-platform: Add platform-specific only when needed
  2. Use environment variables: Abstract platform differences
  3. Test on all platforms: CI should cover all supported platforms
  4. Document limitations: Note which platforms are supported

Next Steps​