Version: 0.1.0-alpha.3

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
`env-file`	`e`	Load environment from file
`env-var`	`E`	Set environment variable
`env-inherit-mode`		Inherit host environment variables: `none`, `allow`, `all`
`env-inherit-allow`		Allowlist host env vars to inherit
`env-inherit-deny`		Denylist host env vars to inherit
`workdir`	`w`	Override working directory
`help`	`h`	Show help
`runtime`	`r`	Override runtime
`from`		Override container image
`force-rebuild`		Force container rebuild
`list`	`l`	List available commands

Best Practices

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

Next Steps

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

Defining Flags​

Flag Properties​

Types​

String (Default)​

Boolean​

Integer​

Float​

Required vs Optional​

Required Flags​

Optional Flags​

Short Aliases​

Validation Patterns​

Accessing in Scripts​

Naming Convention​

Real-World Examples​

Build Command​

Deploy Command​

Flag Syntax Variations​

Reserved Flags​

Best Practices​

Next Steps​