Argumentos Posicionais

Argumentos posicionais são valores passados por posição após o nome do comando. São ideais para entradas obrigatórias onde a ordem é natural (como source e destination).

Definindo Argumentos

{
    name: "copy"
    args: [
        {
            name: "source"
            description: "Source file or directory"
            required: true
        },
        {
            name: "destination"
            description: "Destination path"
            required: true
        }
    ]
    implementations: [...]
}

Uso:

invowk cmd copy ./src ./dest

Propriedades dos Argumentos

Propriedade	Obrigatória	Descrição
name	Sim	Nome do argumento (alfanumérico, hífens, underscores)
description	Sim	Texto de ajuda
type	Não	string, int, float (padrão: string)
default_value	Não	Valor padrão se não fornecido
required	Não	Deve ser fornecido (não pode ter default)
validation	Não	Padrão regex para o valor
variadic	Não	Aceita múltiplos valores (apenas último arg)

Tipos

String (Padrão)

{name: "filename", description: "File to process", type: "string"}

Integer

{name: "count", description: "Number of items", type: "int", default_value: "10"}

invowk cmd generate 5

Float

{name: "ratio", description: "Scaling ratio", type: "float", default_value: "1.0"}

invowk cmd scale 0.5

Nota: Tipo Boolean não é suportado para argumentos. Use flags para opções booleanas.

Obrigatório vs Opcional

Argumentos Obrigatórios

args: [
    {name: "input", description: "Input file", required: true},
    {name: "output", description: "Output file", required: true},
]

# Error: missing required argument
invowk cmd convert input.txt
# Error: argument 'output' is required

# Success
invowk cmd convert input.txt output.txt

Argumentos Opcionais

args: [
    {name: "input", description: "Input file", required: true},
    {name: "format", description: "Output format", default_value: "json"},
]

# Uses default format (json)
invowk cmd parse input.txt

# Override format
invowk cmd parse input.txt yaml

Regra de Ordenação

Argumentos obrigatórios devem vir antes dos argumentos opcionais:

// Good
args: [
    {name: "input", description: "Input file", required: true},      // Required first
    {name: "output", description: "Output file", required: true},     // Required second
    {name: "format", description: "Output format", default_value: "json"}, // Optional last
]

// Bad - will cause validation error
args: [
    {name: "format", description: "Output format", default_value: "json"}, // Optional can't come first
    {name: "input", description: "Input file", required: true},
]

Argumentos Variadic

O último argumento pode aceitar múltiplos valores:

{
    name: "process"
    args: [
        {name: "output", description: "Output file", required: true},
        {name: "inputs", description: "Input files", variadic: true},
    ]
    implementations: [{
        script: """
            echo "Output: $INVOWK_ARG_OUTPUT"
            echo "Inputs: $INVOWK_ARG_INPUTS"
            echo "Count: $INVOWK_ARG_INPUTS_COUNT"

            for i in $(seq 1 $INVOWK_ARG_INPUTS_COUNT); do
                eval "file=$INVOWK_ARG_INPUTS_$i"
                echo "Processing: $file"
            done
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

invowk cmd process out.txt a.txt b.txt c.txt
# Output: out.txt
# Inputs: a.txt b.txt c.txt
# Count: 3
# Processing: a.txt
# Processing: b.txt
# Processing: c.txt

Variáveis de Ambiente para Variadic

Variável	Descrição
INVOWK_ARG_INPUTS	Valores unidos por espaço
INVOWK_ARG_INPUTS_COUNT	Número de valores
INVOWK_ARG_INPUTS_1	Primeiro valor
INVOWK_ARG_INPUTS_2	Segundo valor
...	E assim por diante

Padrões de Validação

Valide valores de argumento com regex:

args: [
    {
        name: "environment"
        description: "Target environment"
        required: true
        validation: "^(dev|staging|prod)$"
    },
    {
        name: "version"
        description: "Version number"
        validation: "^[0-9]+.[0-9]+.[0-9]+$"
    }
]

# Valid
invowk cmd deploy prod 1.2.3

# Invalid
invowk cmd deploy production
# Error: argument 'environment' value 'production' does not match pattern '^(dev|staging|prod)$'

Acessando em Scripts

Variáveis de Ambiente

{
    name: "greet"
    args: [
        {name: "first-name", description: "First name", required: true},
        {name: "last-name", description: "Last name", default_value: "User"},
    ]
    implementations: [{
        script: """
            echo "Hello, $INVOWK_ARG_FIRST_NAME $INVOWK_ARG_LAST_NAME!"
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Convenção de Nomenclatura

Nome do Argumento	Variável de Ambiente
name	INVOWK_ARG_NAME
file-path	INVOWK_ARG_FILE_PATH
outputDir	INVOWK_ARG_OUTPUTDIR

Parâmetros Posicionais do Shell

Argumentos também estão disponíveis como $1, $2, etc.:

{
    name: "copy"
    args: [
        {name: "source", description: "Source path", required: true},
        {name: "dest", description: "Destination path", required: true},
    ]
    implementations: [{
        script: """
            # Using environment variables
            cp "$INVOWK_ARG_SOURCE" "$INVOWK_ARG_DEST"
            
            # Or positional parameters
            cp "$1" "$2"
            
            # All arguments
            echo "Args: $@"
            echo "Count: $#"
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Compatibilidade de Shell

Shell	Acesso Posicional
bash, sh, zsh	$1, $2, $@, $#
PowerShell	$args[0], $args[1]
runtime virtual	$1, $2, $@, $#
container	$1, $2, $@, $#

Exemplos do Mundo Real

Processamento de Arquivo

{
    name: "convert"
    description: "Convert file format"
    args: [
        {
            name: "input"
            description: "Input file"
            required: true
        },
        {
            name: "output"
            description: "Output file"
            required: true
        },
        {
            name: "format"
            description: "Output format"
            default_value: "json"
            validation: "^(json|yaml|toml|xml)$"
        }
    ]
    implementations: [{
        script: """
            echo "Converting $1 to $2 as $3"
            ./converter --input="$1" --output="$2" --format="$3"
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Operação Multi-Arquivo

{
    name: "compress"
    description: "Compress files into archive"
    args: [
        {
            name: "archive"
            description: "Output archive name"
            required: true
            validation: ".(zip|tar.gz|tgz)$"
        },
        {
            name: "files"
            description: "Files to compress"
            variadic: true
        }
    ]
    implementations: [{
        script: """
            if [ -z "$INVOWK_ARG_FILES" ]; then
                echo "No files specified!"
                exit 1
            fi
            
            # Use the space-separated list
            tar -czvf "$INVOWK_ARG_ARCHIVE" $INVOWK_ARG_FILES
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Deploy

{
    name: "deploy"
    description: "Deploy services"
    args: [
        {
            name: "env"
            description: "Target environment"
            required: true
            validation: "^(dev|staging|prod)$"
        },
        {
            name: "replicas"
            description: "Number of replicas"
            type: "int"
            default_value: "1"
        },
        {
            name: "services"
            description: "Services to deploy"
            variadic: true
        }
    ]
    implementations: [{
        script: """
            echo "Deploying to $INVOWK_ARG_ENV with $INVOWK_ARG_REPLICAS replicas"
            
            if [ -n "$INVOWK_ARG_SERVICES" ]; then
                for i in $(seq 1 $INVOWK_ARG_SERVICES_COUNT); do
                    eval "service=$INVOWK_ARG_SERVICES_$i"
                    echo "Deploying $service..."
                    kubectl scale deployment/$service --replicas=$INVOWK_ARG_REPLICAS
                done
            else
                echo "Deploying all services..."
                kubectl scale deployment --all --replicas=$INVOWK_ARG_REPLICAS
            fi
            """
        runtimes: [{name: "native"}]
        platforms: [{name: "linux"}, {name: "macos"}]
    }]
}

Misturando com Flags

Flags podem aparecer em qualquer lugar; argumentos são posicionais:

# All equivalent
invowk cmd deploy prod 3 --dry-run
invowk cmd deploy --dry-run prod 3
invowk cmd deploy prod --dry-run 3

Argumentos são extraídos em ordem, independentemente das posições das flags.

Argumentos vs Subcomandos

Um comando não pode ter ambos argumentos e subcomandos. Se um comando define args mas também tem subcomandos, invowk falha com um erro:

✖ Invalid command structure

Command 'deploy' has both args and subcommands in invowkfile.cue
  defined args: env
  subcommands: deploy status, deploy logs

Remove either the 'args' field or the subcommands to resolve this conflict.

Esta restrição existe porque parsers de CLI interpretam argumentos posicionais após o nome de um comando como potenciais nomes de subcomandos, tornando a combinação ambígua.

Escolha uma abordagem:

• Argumentos: Para comandos folha com entradas diretas
• Subcomandos: Para hierarquias de comando complexas onde usuários selecionam uma ação

Melhores Práticas

1. Args obrigatórios primeiro: Siga as regras de ordenação
2. Use nomes significativos: source e dest não arg1 e arg2
3. Valide quando possível: Capture erros cedo
4. Documente com descrições: Ajude usuários a entender
5. Prefira flags para valores opcionais: Mais fácil de entender

Próximos Passos

• Flags - Para valores opcionais nomeados
• Environment - Configurar ambiente do comando