Pular para o conteúdo principal
Versão: 0.12.0

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
    llm?: #LLMConfig
    container?: #ContainerConfig
}

#IncludeEntry: {
    path:   string  // Must be absolute and end with .invowkmod
    alias?: string  // Optional, for collision disambiguation
}

#VirtualShellConfig: {
    enable_uroot_utils?: bool
}

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

#LLMConfig: {
    provider?: "auto" | "claude" | "codex" | "gemini" | "ollama"
    model?: string
    timeout?: string
    concurrency?: int
    api?: #LLMAPIConfig
}

#LLMAPIConfig: {
    base_url?: string
    model?: string
    api_key_env?: string
}

#ContainerConfig: {
    auto_provision?: #AutoProvisionConfig
}

#AutoProvisionConfig: {
    enabled?: bool
    strict?: bool
    binary_path?: string
    includes?: [...#IncludeEntry]
    inherit_includes?: bool
    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: "podman"

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

includes​

Tipo: [...#IncludeEntry] Padrão: []

Módulos adicionais para incluir na descoberta de comandos. Cada entrada é um #IncludeEntry com path obrigatório (deve terminar com .invowkmod) e alias opcional.

includes: [
    {path: "/home/user/.invowk/modules/tools.invowkmod"},
    {path: "/home/user/projects/shared.invowkmod", alias: "shared"},
    {path: "/opt/company/tools.invowkmod"},
]

Requisitos de caminho:

  • Deve ser absoluto (ex: /home/user/modules/tools.invowkmod)
  • No Windows, use um caminho absoluto Windows (ex: C:\Users\alice\modules\tools.invowkmod ou um caminho UNC)
  • Deve terminar com .invowkmod
  • Caminhos duplicados são rejeitados

Regras de alias:

  • Opcional, para desambiguação de colisões
  • Deve ser único entre todas as entradas includes

Ordem de Descoberta:

  1. invowkfile do diretório atual (sempre buscado primeiro, maior prioridade)
  2. Módulos locais (*.invowkmod no diretório atual)
  3. Cada entrada em includes em ordem
  4. ~/.invowk/cmds/ (apenas módulos, não recursivo)

Quando múltiplos includes definem comandos com o mesmo nome, eles se tornam ambíguos. Use o prefixo @source ou a flag --ivk-from para desambiguar.

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: "native"

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: {enable_uroot_utils: true}

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, 28 comandos adicionais compatíveis com POSIX ficam disponíveis:

Wrappers upstream (12): base64, cat, cp, find, gzip, ls, mkdir, mv, rm, shasum, tar, touch

Implementações customizadas (16): basename, cut, dirname, grep, head, ln, mktemp, realpath, seq, sleep, sort, tail, tee, tr, uniq, wc

Isso torna o virtual shell autocontido, permitindo que scripts executem operações comuns de arquivo, texto e utilitários sem exigir binários externos no sistema host.

dica

Os utilitários u-root são habilitados por padrão. Defina como false apenas se você precisar forçar scripts a usar binários do sistema ou reduzir o tamanho do binário.

ui​

Tipo: #UIConfig Padrão: {color_scheme: "auto", verbose: false, interactive: false}

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

ui: {
    color_scheme: "auto"
    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 --ivk-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 --ivk-interactive na linha de comando.

llm​

Tipo: #LLMConfig Padrão: (não definido)

Configura um backend LLM padrão para comandos que usam LLM. invowk agent cmd create usa essa configuração automaticamente quando nenhuma flag LLM é passada. invowk audit ainda exige opt-in explícito com --llm ou --llm-provider antes de enviar qualquer conteúdo de script para um LLM.

Use um provedor/harness suportado:

llm: {
    provider: "codex"
    model: "gpt-5.1-codex" // optional for CLI harnesses
    timeout: "2m"
    concurrency: 2
}

Ou use um endpoint de API compatível com OpenAI:

llm: {
    api: {
        base_url: "https://api.openai.com/v1"
        model: "gpt-5.1"
        api_key_env: "OPENAI_API_KEY"
    }
}

llm.provider e llm.api são mutuamente exclusivos. Não armazene chaves de API brutas em config.cue; use llm.api.api_key_env para nomear uma variável de ambiente.

llm.provider​

Tipo: "auto" | "claude" | "codex" | "gemini" | "ollama" Padrão: (não definido)

Seleciona um provedor/harness suportado. auto procura Ollama local, credenciais cloud e ferramentas CLI na ordem de provedores.

llm.model​

Tipo: string Padrão: (não definido)

Substitui o modelo usado pelo provedor configurado. Harnesses CLI usam seu próprio padrão atual quando omitido, e fluxos de API/Ollama usam o fallback do resolvedor qwen2.5-coder:7b quando nenhum modelo é configurado ou passado por flag.

llm.timeout​

Tipo: string de duração Go Padrão: (não definido na configuração; fallback do resolvedor: 2m)

Define o timeout por requisição usado por comandos com LLM.

llm.concurrency​

Tipo: int Padrão: (não definido na configuração; fallback do resolvedor: 2)

Limita requisições LLM concorrentes. Defina 0 ou omita o campo para usar o padrão integrado.

llm.api​

Tipo: #LLMAPIConfig Padrão: (não definido)

Configura um endpoint de API compatível com OpenAI usando base_url, model e api_key_env.

llm.api.base_url​

Tipo: string Padrão: (não definido na configuração; fallback do resolvedor: http://localhost:11434/v1)

URL base da API compatível com OpenAI.

llm.api.model​

Tipo: string Padrão: (não definido na configuração; fallback do resolvedor: qwen2.5-coder:7b)

Nome do modelo enviado ao endpoint de API.

llm.api.api_key_env​

Tipo: string Padrão: (não definido)

Nome da variável de ambiente que contém a chave de API.

container​

Tipo: #ContainerConfig Padrão: {auto_provision: {enabled: true, strict: false, inherit_includes: true}}

Configura o comportamento do runtime container.

container: {
    auto_provision: {
        enabled: true
        binary_path: "/usr/local/bin/invowk"
        includes: [
            {path: "/opt/company/modules/tools.invowkmod"},
        ]
        inherit_includes: true
        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.includes​

Tipo: [...#IncludeEntry] Padrão: []

Módulos adicionais para provisionar dentro dos containers. Usa o mesmo formato #IncludeEntry do includes raiz (cada entrada tem um path terminando com .invowkmod e um alias opcional).

container.auto_provision.inherit_includes​

Tipo: bool Padrão: true

Quando true, as entradas de includes do nível raiz são automaticamente herdadas pelo auto-provisionamento. Defina como false para provisionar apenas os módulos listados explicitamente em container.auto_provision.includes.

container.auto_provision.strict​

Tipo: bool Padrão: false

Quando true, falhas de auto-provisionamento são tratadas como erros fatais ao invés de avisos. Por padrão, se o provisionamento falhar, o Invowk exibe um aviso e executa a imagem base. Com strict: true, o comando falha imediatamente em caso de falha de provisionamento.

container.auto_provision.cache_dir​

Tipo: string Padrão: (vazio — usa o padrão específico da plataforma, tipicamente ~/.cache/invowk/provision)

Sobrescreve o diretório pai usado para contextos de build de provisionamento e metadados de imagens em cache.

Exemplo Completo​

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

// Invowk Configuration File
// =========================
// Location: ~/.config/invowk/config.cue

// Container Engine
// ----------------
// Which container runtime to use: "podman" or "docker"
container_engine: "podman"

// Includes
// --------
// Additional modules to include in discovery.
// Each entry specifies a path to an *.invowkmod directory.
// Modules may have an optional alias for collision disambiguation.
includes: [
    // Personal modules
    {path: "/home/user/.invowk/modules/tools.invowkmod"},

    // Team shared module (with alias)
    {path: "/home/user/work/shared.invowkmod", alias: "team"},

    // Organization-wide module
    {path: "/opt/company/tools.invowkmod"},
]

// Default Runtime
// ---------------
// The runtime to use when a command doesn't specify one
// Options: "native", "virtual", "container"
default_runtime: "native"

// Virtual Shell Configuration
// ---------------------------
// Settings for the virtual shell runtime (mvdan/sh)
virtual_shell: {
    // Enable u-root utilities for more shell commands
    // Provides ls, cat, grep, etc. in the virtual environment
    enable_uroot_utils: true
}

// UI Configuration
// ----------------
// User interface settings
ui: {
    // Color scheme: "auto", "dark", or "light"
    // "auto" detects from terminal settings
    color_scheme: "auto"
    
    // Enable verbose output by default
    // Same as always passing --ivk-verbose
    verbose: false

    // Enable interactive mode by default
    interactive: false
}

// Example LLM backend override
// ----------------------------
// Used by invowk agent cmd create and by invowk audit --llm.
// Invowk leaves llm unset by default.
// Bare invowk audit remains deterministic and does not call LLMs.
llm: {
    provider: "codex"
    model: "gpt-5.1-codex"
    timeout: "2m"
    concurrency: 2
}

// Container provisioning
// ----------------------
container: {
    auto_provision: {
        enabled: true
        strict: false
        includes: []
        inherit_includes: true
    }
}