Opções de Configuração

Esta página documenta todas as opções de configuração disponíveis para o Invowk™.

Schema de Configuração

O arquivo de configuração usa o formato CUE e segue este schema:

#Config: {
    container_engine?: "podman" | "docker"
    includes?: [...#IncludeEntry]
    default_runtime?: "native" | "virtual" | "container"
    virtual_shell?: #VirtualShellConfig
    ui?: #UIConfig
    container?: #ContainerConfig
}

#IncludeEntry: {
    path:   string  // Must end with .invkmod, /invkfile.cue, or /invkfile
    alias?: string  // Optional, only valid for .invkmod paths
}

#VirtualShellConfig: {
    enable_uroot_utils?: bool
}

#UIConfig: {
    color_scheme?: "auto" | "dark" | "light"
    verbose?: bool
    interactive?: bool
}

#ContainerConfig: {
    auto_provision?: #AutoProvisionConfig
}

#AutoProvisionConfig: {
    enabled?: bool
    binary_path?: string
    modules_paths?: [...string]
    cache_dir?: string
}

Campos desconhecidos são rejeitados, então mantenha o arquivo de configuração limitado às opções do schema.

Referência de Opções

container_engine

Tipo: "podman" | "docker"
Padrão: "podman"

Especifica qual container runtime usar para execução de comandos baseada em container.

container_engine: "docker"  // or "podman"

Se a engine preferida não estiver disponível, o Invowk faz fallback para a outra quando o runtime container é necessário.

search_paths

Tipo: [...string]
Padrão: []

Diretórios adicionais para buscar invkfiles e módulos. Caminhos são buscados em ordem após o diretório atual.

search_paths: [
    "~/.invowk/modules",
    "~/my-company/shared-modules",
    "/opt/invowk/modules"
]

Ordem de Busca:

1. Diretório atual (sempre buscado primeiro, maior prioridade)
2. Cada caminho em search_paths em ordem
3. ~/.invowk/cmds (sempre incluído)

Comandos de caminhos anteriores sobrescrevem comandos com o mesmo nome de caminhos posteriores.

default_runtime

Tipo: "native" | "virtual" | "container"
Padrão: "native"

Define o modo de runtime padrão global para comandos que não especificam um runtime.

default_runtime: "virtual"

Opções de Runtime:

• "native" - Executar usando o shell nativo do sistema (bash, zsh, PowerShell, etc.)
• "virtual" - Executar usando o interpretador de shell embutido do Invowk (mvdan/sh)
• "container" - Executar dentro de um container (requer Docker ou Podman)

observação

Comandos podem sobrescrever este padrão especificando seu próprio runtime no campo implementations.

virtual_shell

Tipo: #VirtualShellConfig
Padrão: {}

Configura o comportamento do virtual shell runtime.

virtual_shell: {
    enable_uroot_utils: true
}

virtual_shell.enable_uroot_utils

Tipo: bool
Padrão: true

Habilita utilitários u-root no virtual shell. Quando habilitado, comandos adicionais como ls, cat, grep e outros ficam disponíveis no ambiente virtual shell.

virtual_shell: {
    enable_uroot_utils: true
}

Isso é útil quando você quer que o virtual shell tenha mais capacidades além dos builtins básicos de shell, enquanto ainda evita execução de shell nativo.

ui

Tipo: #UIConfig
Padrão: {}

Configura as preferências de interface do usuário.

ui: {
    color_scheme: "dark"
    verbose: false
    interactive: false
}

ui.color_scheme

Tipo: "auto" | "dark" | "light"
Padrão: "auto"

Define o esquema de cores para a saída do Invowk.

ui: {
    color_scheme: "auto"
}

Opções:

• "auto" - Detectar das configurações do terminal (respeita COLORTERM, TERM, etc.)
• "dark" - Usar cores otimizadas para terminais escuros
• "light" - Usar cores otimizadas para terminais claros

ui.verbose

Tipo: bool
Padrão: false

Habilita saída verbose por padrão. Quando habilitado, Invowk imprime informações adicionais sobre descoberta de comandos, validação de dependências e execução.

ui: {
    verbose: true
}

Isso é equivalente a sempre passar --verbose na linha de comando.

ui.interactive

Tipo: bool
Padrão: false

Habilita o modo interativo por padrão. Quando habilitado, os comandos são executados em um buffer de tela alternativo com suporte completo a PTY, permitindo que programas interativos como prompts de senha, confirmações e outras interações baseadas em stdin funcionem corretamente.

ui: {
    interactive: true
}

Isso é equivalente a sempre passar --interactive na linha de comando.

container

Tipo: #ContainerConfig
Padrão: {}

Configura o comportamento do runtime container.

container: {
    auto_provision: {
        enabled: true
        binary_path: "/usr/local/bin/invowk"
        modules_paths: ["/opt/company/invowk-modules"]
        cache_dir: "/tmp/invowk/provision"
    }
}

container.auto_provision.enabled

Tipo: bool
Padrão: true

Habilita o provisionamento automático do binário do invowk e módulos dentro dos containers. Quando habilitado, o Invowk cria uma imagem derivada em cache para cada execução de container, anexando uma pequena camada de provisionamento sobre a imagem base. Se o provisionamento falhar, o Invowk avisa e usa a imagem base.

container.auto_provision.binary_path

Tipo: string
Padrão: (vazio; usa o binário do invowk em execução)

Sobrescreve o caminho do binário do invowk para provisionar.

container.auto_provision.modules_paths

Tipo: [...string] Padrão: []

Diretórios adicionais de módulos para provisionar dentro dos containers.

container.auto_provision.cache_dir

Tipo: string
Padrão: ~/.cache/invowk/provision

Sobrescreve o diretório de cache para metadados de imagens provisionadas.

Exemplo Completo

Aqui está um arquivo de configuração completo com todas as opções:

// Invowk Configuration File
// Located at: ~/.config/invowk/config.cue

// Use Podman as the container engine
container_engine: "podman"

// Additional invkfiles and modules to include in discovery
includes: [
    {path: "~/.invowk/cmds/invkfile.cue"},          // Personal commands
    {path: "~/work/shared.invkmod", alias: "team"},  // Team shared module
]

// Default to virtual shell for portability
default_runtime: "virtual"

// Virtual shell settings
virtual_shell: {
    // Enable u-root utilities for more shell commands
    enable_uroot_utils: true
}

// UI preferences
ui: {
    // Auto-detect color scheme from terminal
    color_scheme: "auto"
    
    // Don't be verbose by default
    verbose: false
    
    // Enable interactive mode for commands with stdin (e.g., password prompts)
    interactive: false
}

// Container provisioning
container: {
    auto_provision: {
        enabled: true
    }
}