Flags and Arguments Overview

Commands can accept user input through flags (named options) and arguments (positional values). Both are passed to your scripts as environment variables.

Quick Comparison

Feature	Flags	Arguments
Syntax	--name=value or --name value	Positional: value1 value2
Order	Any order	Must follow position order
Boolean	Supported (--verbose)	Not supported
Named access	INVOWK_FLAG_NAME	INVOWK_ARG_NAME
Multiple values	No	Yes (variadic)

Example Command

{
    name: "deploy"
    description: "Deploy to an environment"
    
    // Flags - named options
    flags: [
        {name: "dry-run", description: "Preview without applying changes", type: "bool", default_value: "false"},
        {name: "replicas", description: "Number of replicas", type: "int", default_value: "1"},
    ]

    // Arguments - positional values
    args: [
        {name: "environment", description: "Target environment", required: true},
        {name: "services", description: "Services to deploy", variadic: true},
    ]
    
    implementations: [{
        script: """
            echo "Deploying to $INVOWK_ARG_ENVIRONMENT"
            echo "Replicas: $INVOWK_FLAG_REPLICAS"
            echo "Dry run: $INVOWK_FLAG_DRY_RUN"
            echo "Services: $INVOWK_ARG_SERVICES"
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Usage:

invowk cmd deploy production api web --dry-run --replicas=3

Flags

Flags are named options with --name=value syntax:

flags: [
    {name: "verbose", description: "Enable verbose output", type: "bool", short: "v"},
    {name: "output", description: "Output directory", type: "string", short: "o", default_value: "./dist"},
    {name: "count", description: "Number of iterations", type: "int", default_value: "1"},
]

# Long form
invowk cmd build --verbose --output=./build --count=5

# Short form
invowk cmd build -v -o=./build

Key features:

• Support short aliases (-v for --verbose)
• Typed values (string, bool, int, float)
• Optional or required
• Default values
• Regex validation

See Flags for details.

Arguments

Arguments are positional values after the command name:

args: [
    {name: "source", description: "Source directory", required: true},
    {name: "destination", description: "Destination path", default_value: "./output"},
    {name: "files", description: "Files to copy", variadic: true},
]

invowk cmd copy ./src ./dest file1.txt file2.txt

Key features:

• Position-based (order matters)
• Required or optional
• Default values
• Last argument can be variadic (accept multiple values)
• Typed values (string, int, float - but not bool)

See Positional Arguments for details.

Environment Variable Access

Both flags and arguments are available as environment variables:

Flag Variables

Prefix: INVOWK_FLAG_

Flag Name	Environment Variable
verbose	INVOWK_FLAG_VERBOSE
dry-run	INVOWK_FLAG_DRY_RUN
output-file	INVOWK_FLAG_OUTPUT_FILE

Argument Variables

Prefix: INVOWK_ARG_

Argument Name	Environment Variable
environment	INVOWK_ARG_ENVIRONMENT
file-path	INVOWK_ARG_FILE_PATH

Variadic Arguments

Additional variables for multiple values:

Variable	Description
INVOWK_ARG_FILES	Space-separated values
INVOWK_ARG_FILES_COUNT	Number of values
INVOWK_ARG_FILES_1	First value
INVOWK_ARG_FILES_2	Second value

Shell Positional Parameters

Arguments are also available as shell positional parameters:

{
    name: "greet"
    args: [
        {name: "first-name", description: "First name"},
        {name: "last-name", description: "Last name"},
    ]
    implementations: [{
        script: """
            # Using environment variables
            echo "Hello, $INVOWK_ARG_FIRST_NAME $INVOWK_ARG_LAST_NAME!"
            
            # Or using positional parameters
            echo "Hello, $1 $2!"
            
            # All arguments
            echo "All: $@"
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Mixing Flags and Arguments

Flags can appear anywhere on the command line:

# All equivalent
invowk cmd deploy production --dry-run api web
invowk cmd deploy --dry-run production api web
invowk cmd deploy production api web --dry-run

Reserved Flags

Some flag names are reserved by Invowk™:

• ivk-env-file / -e - Load environment from file
• ivk-env-var / -E - Set environment variable
• ivk-env-inherit-mode - Inherit host environment variables
• ivk-env-inherit-allow - Allowlist host env vars to inherit
• ivk-env-inherit-deny - Denylist host env vars to inherit
• ivk-workdir / -w - Override working directory
• ivk-runtime / -r - Override runtime
• ivk-from / -f - Source to run command from
• ivk-force-rebuild - Force container rebuild
• ivk-dry-run - Print execution plan without running
• ivk-watch / -W - Watch mode: re-execute on file changes
• ivk-verbose / -v - Enable verbose output
• ivk-config / -c - Config file path
• ivk-interactive / -i - Run in interactive mode
• help / -h - Show help
• version - Show version information

Additionally, the ivk-, invowk-, and i- prefixes are reserved for system flags. Don't use these prefixes or names for your flags.

Help Output

Flags and arguments appear in command help:

invowk cmd deploy --help

Usage:
  invowk cmd deploy <environment> [services]... [flags]

Arguments:
  environment          (required) - Target environment
  services             (optional) (variadic) - Services to deploy

Flags:
      --dry-run          Perform a dry run (default: false)
  -n, --replicas int     Number of replicas (default: 1)
  -h, --help             help for deploy

Next Steps

• Flags - Named options with --flag=value syntax
• Positional Arguments - Value-based input