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-container-name		Sobrescrever o nome do container persistente de destino (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; exige --ivk-env-inherit-mode=allow (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 nas opções de runtime integradas
• minimal - Estrutura mínima de invowkfile
• full - Template que demonstra subcomandos, flags, configuração de ambiente e dependências de comandos

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-sh

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

# Set virtual runtime options
invowk config set virtual.utilities.enabled 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.git ^1.0.0
invowk module add git@github.com:user/tools.git ~2.1.0 --alias mytools
invowk module add https://github.com/user/monorepo.git ^1.0.0 --path packages/io.example.cli.invowkmod

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, mais parsing de invowkfile e árvore de comandos quando invowkfile.cue está presente)
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 da estrutura e dos metadados do módulo. Quando o módulo contém invowkfile.cue, também faz o parsing do arquivo e valida sua árvore de comandos; módulos apenas de biblioteca não executam essas verificações específicas.

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 system prompts por operação que agentes LLM devem usar ao criar comandos personalizados do Invowk.

invowk agent cmd prompt [operation] [flags]

O argumento opcional operation aceita create, change ou remove. Omita-o para imprimir os prompts das três operações.

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. O name gerado deve corresponder a <name>. Veja Autoria de Agente com LLM para o fluxo completo.

invowk agent cmd create <name> [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
--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

invowk agent cmd change

Gerar uma substituição para um comando personalizado existente com uma LLM. O name gerado deve continuar correspondendo a <name>, e apenas esse comando é substituído.

invowk agent cmd change <name> [description...] [flags]

Flags: iguais a agent cmd create.

invowk agent cmd remove

Remover um comando personalizado de um invowkfile sem resolver um provedor LLM.

invowk agent cmd remove <name> [flags]

Flags:

Flag	Padrão	Descrição
--file	invowkfile.cue	Invowkfile a atualizar
--dry-run	false	Imprimir o patch sem escrever

invowk agent mod prompt

Imprimir system prompts por operação que agentes LLM devem usar ao criar módulos locais do Invowk.

invowk agent mod prompt [operation] [flags]

O argumento opcional operation aceita create, change ou remove. Omita-o para imprimir os prompts das três operações.

Flags:

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

invowk agent mod create

Gerar invowkmod.cue e invowkfile.cue para <module-id>.invowkmod com uma LLM. O ID de módulo gerado deve corresponder a <module-id>.

invowk agent mod create <module-id> [description...] [flags]

Flags:

Flag	Padrão	Descrição
--from-file		Ler a solicitação do módulo a partir de um arquivo
--dry-run	false	Imprimir os patches sem escrever
--print	false	Imprimir o pacote de arquivos gerado sem escrever
--verify	false	Depois de escrever, validar o módulo gerado
--scripts	false	Criar um diretório scripts/ vazio com .gitkeep
--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

invowk agent mod change

Gerar substituições para invowkmod.cue e invowkfile.cue em um módulo local existente. Nenhum outro arquivo do módulo é gerado ou editado.

invowk agent mod change <module-id-or-path> [description...] [flags]

Flags: iguais a agent mod create, exceto que --scripts não é suportado.

invowk agent mod remove

Remover um diretório de módulo local validado sem editar dependências ou lock files. A exclusão exige --force; use --dry-run para visualizar o plano.

invowk agent mod remove <module-id-or-path> [flags]

Flags:

Flag	Padrão	Descrição
--dry-run	false	Imprimir o plano de exclusão sem remover o módulo
--force	false	Excluir o diretório de módulo validado

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 format --llm-provider auto 'add a format command'

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

# Change an existing command
invowk agent cmd change lint --llm-provider claude 'improve the lint command'

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

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

# Author a local module
invowk agent mod create io.example.tools --llm-provider codex 'create project tools'
invowk agent mod change io.example.tools --llm-provider codex 'add formatter'
invowk agent mod remove io.example.tools --dry-run

---

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.