Visão Geral de Flags e Argumentos

Comandos podem aceitar entrada do usuário através de flags (opções nomeadas) e argumentos (valores posicionais). Ambos são passados para seus scripts como variáveis de ambiente.

Comparação Rápida

Recurso	Flags	Argumentos
Sintaxe	--name=value ou --name value	Posicional: value1 value2
Ordem	Qualquer ordem	Deve seguir ordem de posição
Boolean	Suportado (--verbose)	Não suportado
Acesso nomeado	INVOWK_FLAG_NAME	INVOWK_ARG_NAME
Múltiplos valores	Não	Sim (variadic)

Comando de Exemplo

{
    name: "deploy"
    description: "Deploy to an environment"
    
    // Flags - named options
    flags: [
        {name: "dry-run", type: "bool", default_value: "false"},
        {name: "replicas", type: "int", default_value: "1"},
    ]
    
    // Arguments - positional values
    args: [
        {name: "environment", required: true},
        {name: "services", 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"}]
    }]
}

Uso:

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

Flags

Flags são opções nomeadas com sintaxe --name=value:

flags: [
    {name: "verbose", type: "bool", short: "v"},
    {name: "output", type: "string", short: "o", default_value: "./dist"},
    {name: "count", type: "int", default_value: "1"},
]

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

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

Recursos principais:

• Suportam aliases curtos (-v para --verbose)
• Valores tipados (string, bool, int, float)
• Opcional ou obrigatório
• Valores padrão
• Validação por regex

Veja Flags para detalhes.

Argumentos

Argumentos são valores posicionais após o nome do comando:

args: [
    {name: "source", required: true},
    {name: "destination", default_value: "./output"},
    {name: "files", variadic: true},
]

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

Recursos principais:

• Baseado em posição (ordem importa)
• Obrigatório ou opcional
• Valores padrão
• Último argumento pode ser variadic (aceita múltiplos valores)
• Valores tipados (string, int, float - mas não bool)

Veja Positional Arguments para detalhes.

Acesso via Variável de Ambiente

Tanto flags quanto argumentos estão disponíveis como variáveis de ambiente:

Variáveis de Flag

Prefixo: INVOWK_FLAG_

Nome da Flag	Variável de Ambiente
verbose	INVOWK_FLAG_VERBOSE
dry-run	INVOWK_FLAG_DRY_RUN
output-file	INVOWK_FLAG_OUTPUT_FILE

Variáveis de Argumento

Prefixo: INVOWK_ARG_

Nome do Argumento	Variável de Ambiente
environment	INVOWK_ARG_ENVIRONMENT
file-path	INVOWK_ARG_FILE_PATH

Argumentos Variadic

Variáveis adicionais para múltiplos valores:

Variável	Descrição
INVOWK_ARG_FILES	Valores separados por espaço
INVOWK_ARG_FILES_COUNT	Número de valores
INVOWK_ARG_FILES_1	Primeiro valor
INVOWK_ARG_FILES_2	Segundo valor

Parâmetros Posicionais do Shell

Argumentos também estão disponíveis como parâmetros posicionais do shell:

{
    name: "greet"
    args: [
        {name: "first-name"},
        {name: "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"}]
    }]
}

Misturando Flags e Argumentos

Flags podem aparecer em qualquer lugar na linha de comando:

# 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

Flags Reservadas

Alguns nomes de flag são reservados pelo Invowk™:

• ivk-env-file / -e - Carregar ambiente de arquivo
• ivk-env-var / -E - Definir variável de ambiente
• ivk-workdir / -w - Sobrescrever diretório de trabalho
• ivk-runtime / -r - Sobrescrever runtime

Além disso, os prefixos ivk-, invowk- e i- são reservados para flags do sistema. Não use esses prefixos ou nomes para suas flags.

Saída de Ajuda

Flags e argumentos aparecem na ajuda do comando:

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

Próximos Passos

• Flags - Opções nomeadas com sintaxe --flag=value
• Positional Arguments - Entrada baseada em valor