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 sample command. Let's peek inside:

cmds: [
    {
        name: "hello"
        description: "Say hello!"
        implementations: [
            {
                script: "echo 'Hello from Invowk!'"
                runtimes: [{name: "native"}]
                platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
            }
        ]
    }
]

Don't worry about understanding everything yet - we'll cover that soon!

List Available Commands

See what commands are available:

invowk cmd

You'll see something like:

Available Commands
  (* = default runtime)

From current directory:
  hello - Say hello! [native*] (linux, macos, windows)

Commands from the current directory are unprefixed. Module commands will include a module prefix when present.

Run a Command

Now let's run it:

invowk cmd hello

Output:

Hello from Invowk!

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

Let's Make It More Interesting

Edit your invowkfile.cue to add a more useful command:

cmds: [
    {
        name: "hello"
        description: "Say hello!"
        implementations: [
            {
                script: "echo 'Hello from Invowk!'"
                runtimes: [{name: "native"}]
                platforms: [{name: "linux"}, {name: "macos"}, {name: "windows"}]
            }
        ]
    },
    {
        name: "info"
        description: "Show system information"
        implementations: [
            {
                script: """
                    echo "=== System Info ==="
                    echo "User: $USER"
                    echo "Directory: $(pwd)"
                    echo "Date: $(date)"
                    """
                runtimes: [{name: "native"}]
                platforms: [{name: "linux"}, {name: "macos"}]
            }
        ]
    }
]

Now run:

invowk cmd info

You'll see your system information printed out nicely.

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:

{
    name: "cross-platform"
    description: "Works the same everywhere!"
    implementations: [
        {
            script: "echo 'This runs identically on Linux, Mac, and Windows!'"
            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.

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!