Flags

Flags are named options passed with --name=value syntax. They're ideal for optional settings, boolean switches, and configuration that doesn't follow a strict order.

Defining Flags

{
    name: "deploy"
    flags: [
        {
            name: "environment"
            description: "Target environment"
            required: true
        },
        {
            name: "dry-run"
            description: "Simulate without changes"
            type: "bool"
            default_value: "false"
        },
        {
            name: "replicas"
            description: "Number of replicas"
            type: "int"
            default_value: "1"
        }
    ]
    implementations: [...]
}

Flag Properties

Property	Required	Description
name	Yes	Flag name (alphanumeric, hyphens, underscores)
description	Yes	Help text
type	No	string, bool, int, float (default: string)
default_value	No	Default if not provided
required	No	Must be provided (can't have default)
short	No	Single-letter alias
validation	No	Regex pattern for value

Types

String (Default)

{name: "message", description: "Custom message", type: "string"}
// or simply
{name: "message", description: "Custom message"}

invowk cmd run --message="Hello World"

Boolean

{name: "verbose", description: "Enable verbose output", type: "bool", default_value: "false"}

# Enable
invowk cmd run --verbose
invowk cmd run --verbose=true

# Disable (explicit)
invowk cmd run --verbose=false

Boolean flags only accept true or false.

Integer

{name: "count", description: "Number of iterations", type: "int", default_value: "5"}

invowk cmd run --count=10
invowk cmd run --count=-1  # Negative allowed

Float

{name: "threshold", description: "Confidence threshold", type: "float", default_value: "0.95"}

invowk cmd run --threshold=0.8
invowk cmd run --threshold=1.5e-3  # Scientific notation

Required vs Optional

Required Flags

{
    name: "target"
    description: "Deployment target"
    required: true  // Must be provided
}

# Error: missing required flag
invowk cmd deploy
# Error: flag 'target' is required

# Success
invowk cmd deploy --target=production

Required flags cannot have a default_value.

Optional Flags

{
    name: "timeout"
    description: "Request timeout in seconds"
    type: "int"
    default_value: "30"  // Used if not provided
}

# Uses default (30)
invowk cmd request

# Override
invowk cmd request --timeout=60

Short Aliases

Add single-letter shortcuts:

flags: [
    {name: "verbose", description: "Verbose output", type: "bool", short: "v"},
    {name: "output", description: "Output file", short: "o"},
    {name: "force", description: "Force overwrite", type: "bool", short: "f"},
]

# Long form
invowk cmd build --verbose --output=./dist --force

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

# Mixed
invowk cmd build -v --output=./dist -f

Validation Patterns

Validate flag values with regex:

flags: [
    {
        name: "env"
        description: "Environment name"
        validation: "^(dev|staging|prod)$"
        default_value: "dev"
    },
    {
        name: "version"
        description: "Semantic version"
        validation: "^[0-9]+.[0-9]+.[0-9]+$"
    }
]

# Valid
invowk cmd deploy --env=prod --version=1.2.3

# Invalid - fails before execution
invowk cmd deploy --env=production
# Error: flag 'env' value 'production' does not match required pattern '^(dev|staging|prod)$'

Pattern Complexity Limits

Validation patterns have complexity limits to prevent performance issues:

• Maximum pattern length: 1000 characters
• Maximum nested groups: 10 levels
• Excessive repetition operators are detected

Complex patterns like (a+)+ or deeply nested groups will be rejected during validation.

Accessing in Scripts

Flags are available as INVOWK_FLAG_* environment variables:

{
    name: "deploy"
    flags: [
        {name: "env", description: "Environment", required: true},
        {name: "dry-run", description: "Dry run", type: "bool", default_value: "false"},
        {name: "replica-count", description: "Replicas", type: "int", default_value: "1"},
    ]
    implementations: [{
        script: """
            echo "Environment: $INVOWK_FLAG_ENV"
            echo "Dry run: $INVOWK_FLAG_DRY_RUN"
            echo "Replicas: $INVOWK_FLAG_REPLICA_COUNT"
            
            if [ "$INVOWK_FLAG_DRY_RUN" = "true" ]; then
                echo "Would deploy $INVOWK_FLAG_REPLICA_COUNT replicas to $INVOWK_FLAG_ENV"
            else
                ./deploy.sh "$INVOWK_FLAG_ENV" "$INVOWK_FLAG_REPLICA_COUNT"
            fi
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Naming Convention

Flag Name	Environment Variable
env	INVOWK_FLAG_ENV
dry-run	INVOWK_FLAG_DRY_RUN
output-file	INVOWK_FLAG_OUTPUT_FILE
retryCount	INVOWK_FLAG_RETRYCOUNT

Hyphens become underscores, uppercase.

Real-World Examples

Build Command

{
    name: "build"
    description: "Build the application"
    flags: [
        {name: "mode", description: "Build mode", validation: "^(debug|release)$", default_value: "debug"},
        {name: "output", description: "Output directory", short: "o", default_value: "./build"},
        {name: "verbose", description: "Verbose output", type: "bool", short: "v"},
        {name: "parallel", description: "Parallel jobs", type: "int", short: "j", default_value: "4"},
    ]
    implementations: [{
        script: """
            mkdir -p "$INVOWK_FLAG_OUTPUT"
            
            VERBOSE=""
            if [ "$INVOWK_FLAG_VERBOSE" = "true" ]; then
                VERBOSE="-v"
            fi
            
            go build $VERBOSE -o "$INVOWK_FLAG_OUTPUT/app" ./...
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Deploy Command

{
    name: "deploy"
    description: "Deploy to cloud"
    flags: [
        {
            name: "env"
            description: "Target environment"
            short: "e"
            required: true
            validation: "^(dev|staging|prod)$"
        },
        {
            name: "version"
            description: "Version to deploy"
            short: "v"
            validation: "^[0-9]+.[0-9]+.[0-9]+$"
        },
        {
            name: "dry-run"
            description: "Simulate deployment"
            type: "bool"
            short: "n"
            default_value: "false"
        },
        {
            name: "timeout"
            description: "Deployment timeout (seconds)"
            type: "int"
            default_value: "300"
        }
    ]
    implementations: [{
        script: """
            echo "Deploying version ${INVOWK_FLAG_VERSION:-latest} to $INVOWK_FLAG_ENV"
            
            ARGS="--timeout=$INVOWK_FLAG_TIMEOUT"
            if [ "$INVOWK_FLAG_DRY_RUN" = "true" ]; then
                ARGS="$ARGS --dry-run"
            fi
            
            ./scripts/deploy.sh "$INVOWK_FLAG_ENV" $ARGS
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Flag Syntax Variations

All these work:

# Equals sign
--output=./dist

# Space separator
--output ./dist

# Short with equals
-o=./dist

# Short with value
-o ./dist

# Boolean toggle (enables)
--verbose
-v

# Boolean explicit
--verbose=true
--verbose=false

Reserved Flags

Don't use these names - they're reserved by Invowk™:

Flag	Short	Description
ivk-env-file	e	Load environment from file
ivk-env-var	E	Set environment variable
ivk-env-inherit-mode		Inherit host environment variables: none, allow, all
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 (e.g., 'invowkfile' or module name)
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 for your flag names.

Best Practices

1. Use descriptive names: --output-dir not --od
2. Provide defaults when sensible: Reduce required inputs
3. Add validation for constrained values: Fail fast on invalid input
4. Use short aliases for common flags: -v, -o, -f
5. Boolean flags should default to false: Opt-in behavior

Next Steps

• Positional Arguments - For ordered, required values
• Environment - Configure command environment