Referência CLI

Referência completa para todos os comandos e flags de linha de comando do Invowk™.

Flags Globais

Estas flags estão disponíveis para todos os comandos:

Flag	Curta	Descrição
--help	-h	Mostrar ajuda para o comando
--ivk-config	-c	Caminho do arquivo de configuração (padrão: diretório de configuração do SO)
--ivk-interactive	-i	Executar comandos em buffer de tela alternativo (modo interativo)
--ivk-verbose	-v	Habilitar saída verbose
--version		Mostrar informação de versão (apenas no comando raiz, não herdado por subcomandos)

Comandos

invowk

O comando raiz. Executar invowk sem argumentos mostra a mensagem de ajuda.

invowk [flags]
invowk [command]

---

invowk cmd

Executar comandos definidos em invowkfiles.

invowk cmd [flags]
invowk cmd [command-name] [flags] [-- args...]

Flags:

Flag	Curta	Descrição
--ivk-runtime	-r	Sobrescrever o runtime (deve ser permitido pelo comando)
--ivk-from	-f	Origem para executar comando (ex.: 'invowkfile' ou nome do módulo)
--ivk-force-rebuild		Forçar reconstrução de imagens de container (somente runtime container)
--ivk-dry-run		Imprimir plano de execução resolvido sem executar
--ivk-watch	-W	Modo watch: reexecutar ao detectar mudanças em arquivos

Flags embutidas por comando:

Flag	Curta	Descrição
--ivk-env-file	-e	Carregar variáveis de ambiente de arquivo (repetível)
--ivk-env-var	-E	Definir variável de ambiente (KEY=VALUE, repetível)
--ivk-env-inherit-mode		Herdar variáveis do host: none, allow, all
--ivk-env-inherit-allow		Allowlist de variáveis do host (repetível)
--ivk-env-inherit-deny		Denylist de variáveis do host (repetível)
--ivk-workdir	-w	Sobrescrever diretório de trabalho do comando

observação

Os prefixos ivk-, invowk- e i- são reservados para flags do sistema e não podem ser usados para flags definidas pelo usuário.

Exemplos:

# List all available commands
invowk cmd

# Run a command
invowk cmd build

# Run a nested command
invowk cmd test unit

# Run with a specific runtime
invowk cmd build --ivk-runtime container

# Run with arguments
invowk cmd greet -- "World"

# Run with flags
invowk cmd deploy --env production

# Watch mode (re-execute on file changes)
invowk cmd dev --ivk-watch
invowk cmd dev -W

# Dry-run mode (print execution plan, don't execute)
invowk cmd build --ivk-dry-run

Descoberta de Comandos:

Comandos são descobertos de (em ordem de prioridade):

1. invowkfile.cue do diretório atual (prioridade mais alta)
2. Diretórios *.invowkmod irmãos
3. Entradas configuradas em includes (somente módulos)
4. ~/.invowk/cmds/ (somente módulos, não-recursivo)

Desambiguação de Comandos:

Quando um nome de comando existe em múltiplas origens (ex.: tanto em invowkfile.cue quanto em um módulo), você deve desambiguar:

Usando o prefixo @source:

invowk cmd @invowkfile deploy      # Executar deploy do invowkfile
invowk cmd @tools deploy         # Executar deploy de tools.invowkmod
invowk cmd @tools.invowkmod deploy # Nome completo do módulo também funciona

Usando a flag --ivk-from:

invowk cmd --ivk-from invowkfile deploy
invowk cmd --ivk-from tools deploy

Se você executar um comando ambíguo sem desambiguação, o invowk mostra um erro listando as origens disponíveis.

dica

Você pode usar @source ou --ivk-from mesmo para nomes de comando únicos para ser explícito sobre de onde um comando vem.

---

invowk init

Criar um novo invowkfile no diretório atual.

invowk init [flags] [filename]

Opcionalmente, passe um nome de arquivo customizado para gravar.

Flags:

Flag	Curta	Descrição
--force	-f	Sobrescrever invowkfile existente
--template	-t	Template a usar: default, minimal, full

Templates:

• default - Um comando hello demonstrando o padrão de divisão por plataforma nos três runtimes
• minimal - Estrutura mínima de invowkfile
• full - Template abrangente mostrando todas as funcionalidades

Exemplos:

# Create a default invowkfile
invowk init

# Create a minimal invowkfile
invowk init --template minimal

# Overwrite existing invowkfile
invowk init --force

---

invowk config

Gerenciar configuração do Invowk.

invowk config [command]

Subcomandos:

invowk config show

Exibir configuração atual em formato legível.

invowk config show

invowk config dump

Exibir configuração raw como CUE.

invowk config dump

invowk config path

Mostrar caminhos de configuração (diretório de configuração, arquivo e diretório de comandos).

invowk config path

invowk config init

Criar um arquivo de configuração padrão.

invowk config init

invowk config set

Definir um valor de configuração.

invowk config set <key> <value>

Exemplos:

# Set container engine
invowk config set container_engine podman

# Set default runtime
invowk config set default_runtime virtual

# Set UI options
invowk config set ui.color_scheme dark
invowk config set ui.verbose true
invowk config set ui.interactive false

# Set virtual shell options
invowk config set virtual_shell.enable_uroot_utils true

---

invowk module

Gerenciar módulos do invowk (pastas de comandos autocontidas).

:::tip Alias mod é um alias para module. Por exemplo, invowk mod list funciona da mesma forma que invowk module list. :::

invowk module [command]

Subcomandos:

invowk module create

Criar um novo módulo do invowk.

invowk module create <name> [flags]

Flags:

Flag	Curta	Descrição
--path	-p	Diretório pai do módulo (padrão: diretório atual)
--scripts		Criar um subdiretório scripts/
--module-id	-g	Identificador do módulo em invowkmod.cue (padrão: nome do módulo)
--description	-d	Descrição para invowkmod.cue

Exemplos:

# Create a module with RDNS naming
invowk module create com.example.mytools

# Override module ID and description
invowk module create mytools --module-id com.example.tools --description "Shared tools"

# Create with scripts directory
invowk module create mytools --scripts

invowk module list

Listar todos os módulos descobertos.

invowk module list

invowk module archive

Criar um arquivo ZIP de um módulo.

invowk module archive <path> [flags]

Flags:

Flag	Curta	Descrição
--output	-o	Caminho do arquivo de saída

invowk module import

Importar um módulo de um arquivo ZIP ou URL.

invowk module import <source> [flags]

Flags:

Flag	Curta	Descrição
--path	-p	Diretório de saída
--overwrite		Sobrescrever módulo existente, se presente

invowk module add

Resolver uma dependência de módulo, atualizar o lock file e adicionar o requisito ao invowkmod.cue.

invowk module add <git-url> <version> [flags]

Flags:

Flag	Descrição
--alias	Alias para o ID de origem de comando do módulo
--path	Subdiretório dentro do repositório

Exemplos:

invowk module add https://github.com/user/utils.invowkmod.git ^1.0.0
invowk module add git@github.com:user/tools.invowkmod.git ~2.1.0 --alias mytools
invowk module add https://github.com/user/monorepo.git ^1.0.0 --path packages/cli

invowk module remove

Remover uma dependência de módulo tanto do lock file quanto do invowkmod.cue.

invowk module remove <identifier>

invowk module sync

Sincronizar dependências de invowkmod.cue.

invowk module sync

invowk module update

Atualizar dependências de módulo para as versões mais recentes compatíveis.

invowk module update [identifier]

invowk module tidy

Adicionar dependências transitivas faltantes ao invowkmod.cue. O Invowk usa um modelo de dependências explícitas (como Go modules): todo módulo na árvore de dependências deve ser declarado no invowkmod.cue raiz. Este comando verifica os módulos resolvidos e adiciona automaticamente os requisitos transitivos faltantes.

invowk module tidy

invowk module deps

Listar dependências de módulo resolvidas.

invowk module deps

invowk module vendor

Fazer vendor de dependências em invowk_modules/.

invowk module vendor [module-path]

Flags:

Flag	Descrição
--update	Forçar re-fetch de todas as dependências
--prune	Remover módulos vendorizados não usados

observação

invowk module vendor resolve as dependências e as copia para invowk_modules/. Se invowkmod.lock.cue existir, o vendor usa por padrão as versões travadas. Use --update para forçar nova resolução e --prune para remover módulos vendorizados obsoletos.

---

invowk tui

Componentes de interface de terminal interativos para shell scripts.

invowk tui [command] [flags]

dica

Componentes TUI funcionam muito bem em scripts de invowkfile! Eles oferecem prompts interativos, spinners, file pickers e mais.

Subcomandos:

invowk tui input

Prompt para entrada de texto em uma linha.

invowk tui input [flags]

Flags:

Flag	Descrição
--title	Título do prompt
--description	Descrição abaixo do título
--placeholder	Texto placeholder
--value	Valor inicial
--char-limit	Limite de caracteres
--width	Largura do campo de entrada
--password	Esconder entrada (para senhas)
--prompt	Caractere(s) do prompt antes da entrada

invowk tui write

Editor de texto multi-linha.

invowk tui write [flags]

Flags:

Flag	Descrição
--title	Título do editor
--description	Descrição abaixo do título
--placeholder	Texto placeholder
--value	Valor inicial
--char-limit	Limite de caracteres
--width	Largura do editor
--height	Altura do editor
--show-line-numbers	Mostrar números de linha

invowk tui choose

Selecionar de uma lista de opções.

invowk tui choose [options...] [flags]

Flags:

Flag	Descrição
--title	Título da seleção
--limit	Número máximo de seleções (padrão: 1)
--no-limit	Permite seleções ilimitadas
--height	Altura da lista

invowk tui confirm

Prompt de confirmação sim/não.

invowk tui confirm [prompt] [flags]

Flags:

Flag	Descrição
--title	Título exibido acima do prompt
--default	Usar sim como padrão quando presente
--affirmative	Texto para opção "sim"
--negative	Texto para opção "não"

invowk tui filter

Filtrar uma lista de opções com fuzzy matching.

invowk tui filter [options...] [flags]

Opções também podem ser fornecidas via stdin.

Flags:

Flag	Descrição
--title	Título exibido acima do filtro
--placeholder	Texto placeholder
--width	Largura do filtro
--height	Altura da lista
--limit	Máximo de seleções (padrão: 1)
--no-limit	Permite seleções ilimitadas
--reverse	Exibe a lista em ordem reversa
--fuzzy	Habilita fuzzy matching

invowk tui file

Seletor de arquivos.

invowk tui file [path] [flags]

Flags:

Flag	Descrição
--title	Título exibido acima do seletor
--description	Descrição abaixo do título
--directory	Mostrar apenas diretórios
--file	Mostrar arquivos (padrão: verdadeiro)
--hidden	Mostrar arquivos ocultos
--height	Altura do seletor
--allowed	Extensões permitidas

invowk tui table

Exibir e selecionar de uma tabela.

invowk tui table [flags]

Lê dados CSV ou TSV de arquivo ou stdin.

Flags:

Flag	Descrição
--file	Arquivo CSV para exibir
--separator	Separador de colunas (padrão: ,)
--columns	Cabeçalhos das colunas (sobrescreve cabeçalho do arquivo)
--widths	Larguras de coluna
--height	Altura da tabela
--selectable	Habilita seleção de linhas

invowk tui spin

Mostrar um spinner enquanto executa um comando.

invowk tui spin [flags] -- command [args...]

Flags:

Flag	Descrição
--title	Título do spinner
--type	Estilo do spinner

invowk tui pager

Scroll por conteúdo.

invowk tui pager [file] [flags]

Lê de arquivo ou stdin.

Flags:

Flag	Descrição
--title	Título exibido acima do pager
--line-numbers	Mostrar números de linha
--soft-wrap	Quebra suave de linhas longas

invowk tui format

Formatar texto com markdown, código, emoji ou templates.

invowk tui format [text...] [flags]

Flags:

Flag	Descrição
--type	Tipo de formatação: markdown, code, emoji, template
--language	Linguagem para highlight de código
--theme	Tema do Glamour para highlight de código

invowk tui style

Aplicar estilos ao texto.

invowk tui style [text...] [flags]

Flags:

Flag	Descrição
--foreground	Cor do texto (hex ou nome)
--background	Cor do fundo
--bold	Texto em negrito
--italic	Texto em itálico
--underline	Texto sublinhado
--strikethrough	Texto tachado
--faint	Texto esmaecido
--blink	Texto piscando
--reverse	Cores invertidas
--margin-*	Margens (esquerda/direita/topo/baixo)
--padding-*	Padding (esquerda/direita/topo/baixo)
--width	Largura fixa
--height	Altura fixa
--align	Alinhamento de texto
--border	Estilo da borda: none, normal, rounded, double, thick, hidden

---

invowk validate

Validar invowkfiles, módulos ou o workspace inteiro.

invowk validate [path]

Sem argumentos, valida o workspace atual executando a descoberta completa e reportando todos os diagnósticos de cada caminho de busca.

Com um argumento de caminho, detecta automaticamente o tipo do alvo:

Caminho	Validação
Diretório *.invowkmod	Validação de módulo (estrutura + parsing de invowkfile + árvore de comandos)
Arquivo invowkfile.cue	Validação de invowkfile (schema CUE + estrutural + árvore de comandos)
Diretório com invowkfile.cue	Validação de invowkfile
Arquivo invowkmod.cue	Validação de módulo (diretório pai)

dica

invowk validate sempre executa validação profunda em módulos, incluindo parsing de invowkfile e verificações da árvore de comandos.

Exemplos:

# Validate the entire workspace (discovery + diagnostics)
invowk validate

# Validate a single invowkfile
invowk validate ./invowkfile.cue

# Validate a module (always includes deep validation)
invowk validate ./mymod.invowkmod

# Validate a directory containing an invowkfile
invowk validate ./my-project/

---

invowk audit

Escanear riscos de segurança em invowkfiles, módulos e scripts. Veja o guia de Auditoria de Segurança para documentação completa.

invowk audit [path] [flags]

Flags:

Flag	Padrão	Descrição
--format	text	Formato de saída: text, json
--severity	low	Severidade mínima: info, low, medium, high, critical
--include-global	false	Incluir ~/.invowk/cmds/ no scan
--llm-provider		Auto-detectar ou forçar provedor: auto, claude, codex, gemini, ollama
--llm	false	Habilitar LLM usando configuração ou API
--llm-url	http://localhost:11434/v1	URL base da API compatível com OpenAI
--llm-model	Fallback de API/Ollama: qwen2.5-coder:7b; padrão da ferramenta para provedor CLI quando omitido	Nome do modelo; obrigatório para provedores de API cloud e opcional para provedores CLI
--llm-api-key	(vazio)	Chave de API (vazio para servidores locais)
--llm-timeout	2m	Timeout por requisição
--llm-concurrency	2	Máximo de requisições LLM paralelas

--llm e --llm-provider são mutuamente exclusivos. Use --llm para o backend configurado/API e --llm-provider para forçar a detecção de provedor.

Códigos de saída: 0 = limpo, 1 = achados detectados, 2 = erro de scan.

Exemplos:

# Scan current workspace
invowk audit

# Scan a single module
invowk audit ./tools.invowkmod

# Scan with high severity threshold
invowk audit --severity high

# JSON output for CI pipelines
invowk audit --format json --severity high

# Include global modules in scan
invowk audit --include-global

# Auto-detect LLM provider
invowk audit --llm-provider auto

# Use specific provider (Claude Code, Codex CLI, Gemini CLI)
invowk audit --llm-provider claude

# Manual LLM with custom server
invowk audit --llm --llm-url http://localhost:1234/v1

---

invowk agent cmd prompt

Imprimir o system prompt que agentes LLM devem usar ao criar um comando personalizado do Invowk.

invowk agent cmd prompt [flags]

Flags:

Flag	Padrão	Descrição
--format	text	Formato de saída: text, json

invowk agent cmd create

Gerar um comando personalizado com uma LLM, validá-lo e aplicar o patch em invowkfile.cue. Veja Autoria de Comandos com LLM para o fluxo completo.

invowk agent cmd create [description...] [flags]

Flags:

Flag	Padrão	Descrição
--file	invowkfile.cue	Invowkfile a atualizar
--from-file		Ler a solicitação do comando a partir de um arquivo
--dry-run	false	Imprimir o patch sem escrever
--print	false	Imprimir apenas o CUE do comando gerado
--replace	false	Substituir um comando existente com o mesmo nome
--verify	false	Depois de escrever, resolver o comando gerado com um plano de execução dry-run
--llm-provider		Auto-detectar ou forçar provedor: auto, claude, codex, gemini, ollama
--llm	false	Habilitar LLM usando configuração ou API
--llm-url	http://localhost:11434/v1	URL base da API compatível com OpenAI
--llm-model	Fallback de API/Ollama: qwen2.5-coder:7b; padrão da ferramenta para provedor CLI quando omitido	Nome do modelo; obrigatório para provedores de API cloud e opcional para provedores CLI
--llm-api-key	(vazio)	Chave de API (vazio para servidores locais)
--llm-timeout	2m	Timeout por requisição
--llm-concurrency	2	Máximo de requisições LLM paralelas

Forneça argumentos de descrição ou --from-file; eles são mutuamente exclusivos. --llm e --llm-provider são mutuamente exclusivos. --dry-run e --print são mutuamente exclusivos. --verify exige escrever o invowkfile e não pode ser combinado com --dry-run ou --print. A verificação atualmente só aceita o alvo do diretório atual (./invowkfile.cue); combinar --verify com --file para outro caminho falha antes de resolver o plano de execução dry-run.

Exemplos:

# Print the command-authoring system prompt
invowk agent cmd prompt

# Generate and add a command with provider auto-detection
invowk agent cmd create --llm-provider auto 'add a format command'

# Preview instead of writing
invowk agent cmd create --llm-provider codex --dry-run 'add a test command'

# Replace an existing command with the same name
invowk agent cmd create --llm-provider claude --replace 'improve the lint command'

# Verify the written command can resolve to an execution plan
invowk agent cmd create --llm-provider codex --verify 'add a release command'

# Read the request from a file
invowk agent cmd create --llm-provider gemini --from-file command-request.md

---

invowk completion

Gerar scripts de completion para o shell.

invowk completion [shell]

Shells: bash, zsh, fish, powershell

Exemplos:

# Bash
eval "$(invowk completion bash)"

# Zsh
eval "$(invowk completion zsh)"

# Fish
invowk completion fish > ~/.config/fish/completions/invowk.fish

# PowerShell
invowk completion powershell | Out-String | Invoke-Expression

---

invowk help

Mostrar ajuda para qualquer comando.

invowk help [command]

Exemplos:

invowk help
invowk help cmd
invowk help config set

Exit Codes

Invowk termina com:

• 0 em sucesso
• 1 em erros de CLI ou runtime
• O código de saída do comando executado quando um comando ou tui spin falha

Mensagens de Erro

O Invowk fornece mensagens específicas para ajudar no diagnóstico:

Nenhum Invowkfile Encontrado

Quando nenhum invowkfile é descoberto em nenhum local de busca:

# No invowkfile found!

We searched for an invowkfile but couldn't find one in the expected locations.

## Search locations (in order of precedence):
1. Current directory (invowkfile and sibling modules)
2. Configured includes (module paths from config)
3. ~/.invowk/cmds/ (modules only)

## Things you can try:
• Create an invowkfile in your current directory:
  $ invowk init

• Or specify a different directory:
  $ cd /path/to/your/project

Esta mensagem aparece quando:

• Nenhum invowkfile.cue existe no diretório atual
• Nenhum módulo existe nos includes configurados
• Nenhum módulo existe em ~/.invowk/cmds/

Soluções:

• Execute invowk init para criar um invowkfile no diretório atual
• Navegue para um diretório que contenha um invowkfile
• Adicione caminhos de módulo em includes na sua configuração

Falha ao Fazer Parse do Invowkfile

Quando um invowkfile é encontrado mas contém erros de sintaxe ou configuração inválida:

✗ Failed to parse /path/to/invowkfile.cue: invowkfile validation failed:
  #Invowkfile.cmds.0.implementations.0.runtimes.0.name: 3 errors in empty disjunction

# Failed to parse invowkfile!

Your invowkfile contains syntax errors or invalid configuration.

## Common issues:
- Invalid CUE syntax (missing quotes, braces, etc.)
- Unknown field names
- Invalid values for known fields
- Missing required fields (name, script for commands)

## Things you can try:
- Check the error message above for the specific line/column
- Validate your CUE syntax using the cue command-line tool
- Run with verbose mode for more details:
  $ invowk --ivk-verbose cmd

Esta mensagem aparece quando:

• Erros de sintaxe CUE (chaves/aspas faltando, etc.)
• Nomes de campo ou valores inválidos
• Falhas de validação do schema (ex.: tipo de runtime inválido)
• Campos obrigatórios ausentes

Soluções:

• Verifique a mensagem de erro específica exibida acima do texto de ajuda
• Valide sua sintaxe CUE: cue vet invowkfile.cue
• Rode com modo verbose: invowk --ivk-verbose cmd
• Compare com a referência de schema do invowkfile

dica

A mensagem de erro sempre mostra primeiro o erro de parse específico (por exemplo, qual campo falhou na validação), seguido por orientações gerais de troubleshooting.