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 (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) |
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 |
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):
invowkfile.cuedo diretório atual (prioridade mais alta)- Diretórios
*.invowkmodirmãos - Entradas configuradas em
includes(somente módulos) ~/.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.
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 template equilibrado com alguns comandos de exemplominimal- Estrutura mínima de invowkfilefull- 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).
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 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, 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 namespace 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 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 |
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]
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) |
Diferente de invowk module validate, invowk validate sempre executa validação profunda
(incluindo parsing de invowkfile e verificações da árvore de comandos) sem necessitar da flag --deep.
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 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:
0em sucesso1em erros de CLI ou runtime- O código de saída do comando executado quando um comando ou
tui spinfalha
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.cueexiste no diretório atual - Nenhum módulo existe nos
includesconfigurados - Nenhum módulo existe em
~/.invowk/cmds/
Soluções:
- Execute
invowk initpara criar um invowkfile no diretório atual - Navegue para um diretório que contenha um invowkfile
- Adicione caminhos de módulo em
includesna 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
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.