Quickstart

Let's run your first Invowk™ command in under 2 minutes. Seriously, grab a coffee first if you want - you'll have time to spare.

Create Your First Invowkfile

Navigate to any project directory and initialize an invowkfile:

cd my-project
invowk init

This creates an invowkfile.cue with a hello command that works across all three runtimes (native, virtual, and container). Let's peek inside:

// Invowkfile - Command definitions for invowk
// See https://github.com/invowk/invowk for documentation

cmds: [
    {
        name: "hello"
        description: "Print a greeting"
        implementations: [
            {
                script: "echo "Hello, $INVOWK_ARG_NAME!""
                runtimes: [{name: "native"}]
                platforms: [{name: "linux"}, {name: "macos"}]
            },
            {
                script: "Write-Output "Hello, $($env:INVOWK_ARG_NAME)!""
                runtimes: [{name: "native"}]
                platforms: [{name: "windows"}]
            },
            {
                script: "echo "Hello, $INVOWK_ARG_NAME!""
                runtimes: [{name: "virtual"}]
                platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
            },
            {
                script: "echo "Hello from container, $INVOWK_ARG_NAME!""
                runtimes: [{name: "container", image: "debian:stable-slim"}]
                platforms: [{name: "linux"}]
            },
        ]
        args: [
            {name: "name", description: "Who to greet", default_value: "World"},
        ]
    },
]

The default template gives you a single hello command with four implementations: native (Unix and Windows), virtual (cross-platform), and container. Each implementation declares which platforms it supports.

List Available Commands

See what commands are available:

invowk cmd

You'll see something like:

Available Commands
  (* = default runtime)

From invowkfile:
  hello - Print a greeting [native*, virtual, container] (linux, macos, windows)

The listing shows the command name, description, allowed runtimes (default marked with *), and supported platforms.

Run a Command

Now let's run one:

invowk cmd hello

Output:

Hello, World!

That's it! You just ran your first Invowk command.

Pass an Argument

The hello command accepts an optional name argument (defaulting to "World"). Try passing your name:

# Pass an argument to the hello command
invowk cmd hello Alice

# Use a different runtime
invowk cmd hello --ivk-runtime virtual

Output:

Hello, Alice!

Arguments are exposed as INVOWK_ARG_<NAME> environment variables, making them accessible from any runtime.

Try the Virtual Runtime

One of Invowk's superpowers is the virtual runtime - a built-in shell interpreter that works the same on every platform:

// The virtual runtime uses the built-in mvdan/sh interpreter
// It works identically on Linux, macOS, and Windows
{
    script: "echo "Hello, $INVOWK_ARG_NAME!""
    runtimes: [{name: "virtual"}]
    platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
}

The virtual runtime uses the mvdan/sh interpreter, giving you consistent POSIX shell behavior across all platforms - no need for separate Unix and Windows implementations.

What's Next?

You've just scratched the surface! Head to Your First Invowkfile to learn how to build more powerful commands with:

• Multiple runtime options (native, virtual, container)
• Dependencies that are validated before running
• Command flags and arguments
• Environment variables
• And much more!