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: $HOME/.config/invowk/config.cue)
--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

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)

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

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)

---

invowk init

Criar um novo invowkfile no diretório atual.

invowk init [flags] [path]

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 template equilibrado com alguns comandos de exemplo
• 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 o caminho do arquivo de configuração.

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 nested value
invowk config set ui.color_scheme dark

---

invowk module

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

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 validate

Validar um módulo do invowk.

invowk module validate <path> [flags]

Flags:

Flag	Curta	Descrição
--deep		Também valida a sintaxe do invowkfile

Exemplos:

# Basic validation
invowk module validate ./mymod.invowkmod

# Deep validation
invowk module validate ./mymod.invowkmod --deep

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 e imprimir a entrada requires para invowkmod.cue.

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

Flags:

Flag	Descrição
--alias	Alias para o namespace do módulo
--path	Subdiretório dentro do repositório

invowk module remove

Remover uma dependência de módulo do lock file.

invowk module remove <git-url>

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 [git-url]

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

Vendoring atualmente é uma funcionalidade em preview. O comando reporta o que seria vendorizado e cria a estrutura de diretórios, mas ainda não faz download das dependências.

---

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	Valor padrão (true/false)
--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 apenas arquivos
--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

---

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.