Referência da CLI

Interface de linha de comando para o runtime do Wippy.

Flags Globais

Disponíveis em todos os comandos:

Prioridade do limite de memória: flag --memory-limit > variável de ambiente GOMEMLIMIT > padrão de 1GB.

--config pode ser passado múltiplas vezes para compor arquivos de configuração. Os arquivos são mesclados da esquerda para a direita: arquivos posteriores sobrescrevem valores correspondentes e mantêm todo o resto. Todo arquivo nomeado explicitamente deve existir; sem --config, o .wippy.yaml padrão é opcional. O primeiro arquivo ancora o diretório usado para resolver caminhos relativos. A configuração é aplicada em ordem: composição de arquivos, seleções de --profile e sobrescritas de --set. Consulte Configuração.

wippy publish oculta a opção global com uma opção local --config <dir>. Nesse comando, o valor é o diretório que contém wippy.yaml, não um arquivo repetível de configuração do runtime.

wippy init

Criar um novo arquivo de lock.

wippy init
wippy init --src-dir ./src --modules-dir .wippy

wippy run

Iniciar o runtime ou executar um comando.

wippy run                                   # Start runtime
wippy run list                              # List available commands
wippy run migrate                           # Run a named custom command
wippy run snapshot.wapp                     # Run from pack file
wippy run acme/http                         # Run module from hub
wippy run acme/http@1.2.3                   # Run specific version
wippy run --exec app:worker                 # Start runtime and execute a single process

Executar um módulo do hub (wippy run org/module) o resolve uma vez, registra-o no wippy.lock e vendoriza localmente os packs verificados. Execuções subsequentes da mesma referência partem do lock — sem necessidade de rede. Um seletor de versão que não corresponde mais ao lock é rejeitado com uma dica para executar wippy update.

Para uma aplicação local, wippy run repara um lock desatualizado antes de qualquer serviço do runtime iniciar. Ele carrega as declarações de dependência das fontes e, quando o lock já as satisfaz, re-resolve o grafo apenas a partir de evidências locais e instaladas (acesso verificado offline, sem rede). Se essa resolução offline corresponde ao lock, o boot continua inalterado. Se ela tem sucesso mas difere, ela se torna o grafo candidato; o hub só é chamado para resolver quando a passagem offline falha ou o lock já não satisfaz as declarações das fontes. Os packs que faltam ao grafo candidato são baixados e verificados, e só então o wippy.lock é reescrito. Um lock que seleciona uma raiz de deployment é autoritativo e nunca é re-resolvido.

--exec bloqueia até o processo lançado produzir seu resultado, e então propaga o código de saída do processo como código de saída da CLI. Ctrl-C durante --exec cancela o processo em execução e o runtime ainda encerra graciosamente; um segundo sinal força a saída.

--set escreve qualquer valor de configuração do runtime pela linha de comando, mesclado sobre .wippy.yaml por folha:

wippy run --set cluster.enabled=true \
          --set cluster.membership.join_addrs=node-2:7946,node-3:7946 \
          --set cluster.raft.bootstrap_expect=3

Os valores são convertidos pelo formato: true/false para bool, inteiros e floats para números, o restante permanece string (durações como 5s são analisadas onde a opção espera uma).

wippy test

Executar o entrypoint de teste: a entrada de processo que declara o use case test. O runtime inicia, executa essa entrada e encerra. wippy run não executa automaticamente entrypoints de teste; testes sempre passam por wippy test.

wippy test                     # Run tests from the local project
wippy test snapshot.wapp       # Run tests from a pack file
wippy test acme/module@1.2.3   # Run tests from a hub module

wippy lint

Verificar erros de tipo e avisos no código Lua.

wippy lint
wippy lint --level warning
wippy lint --json
wippy lint --rules

Valida todas as entradas Lua: function.lua, library.lua, process.lua, workflow.lua (incluindo suas variantes .bc).

wippy add

Adicionar uma dependência de módulo.

wippy add acme/http
wippy add acme/http@1.2.3
wippy add acme/http@latest

wippy install

Instalar dependências a partir do arquivo de lock.

wippy install                            # Install all
wippy install acme/http                  # Install specific module
wippy install --refresh acme/http        # Re-fetch a specific module

wippy update

Atualizar dependências e regenerar o arquivo de lock.

wippy update                      # Update all
wippy update acme/http            # Update specific module
wippy update acme/http demo/sql   # Update multiple

wippy artifacts

Trabalhar com artefatos de sistema de arquivos gerados em tempo de build.

wippy artifacts materialize

Validar e materializar um sistema de arquivos de artefato a partir de um pack existente.

wippy artifacts materialize snapshot.wapp app:package_fs
wippy artifacts materialize snapshot.wapp app:package_fs --root build

O recurso é endereçado por seu namespace:name completo, deve declarar meta.artifact.format, e esse formato deve estar registrado na CLI. O comando não resolve dependências de módulos, não altera o wippy.lock, não invoca gerenciadores de pacotes e não participa da composição do runtime. Veja Artefatos de build.

wippy pack

Criar um pack de snapshot (arquivo .wapp).

wippy pack snapshot.wapp
wippy pack release.wapp --description "Release 1.0"
wippy pack app.wapp --embed app:assets --bytecode "**"

Sem --embed nem --embed-all, os padrões de incorporação recorrem à seção embed: do manifesto de módulo wippy.yaml. Empacotar uma aplicação também carrega os recursos incorporados dos packs de suas dependências, e apenas os comandos do módulo principal são expostos pelo pack resultante.

O arquivo de saída é escrito atomicamente: o pack é construído em um arquivo temporário no diretório de destino, sincronizado, verificado, e só então renomeado sobre o alvo, herdando as permissões do arquivo existente quando há um. Um pack que falha deixa o arquivo anterior intocado. Nomear uma saída que também é uma das entradas do pack — o mesmo caminho, ou um hard link ou symlink que resolve para o mesmo arquivo — é recusado em vez de truncar a entrada durante a leitura.

--meta não pode escrever metadados reservados. A chave registry, e qualquer coisa sob os prefixos wippy. ou system., pertence ao formato do pack e é rejeitada.

Recursos que declaram meta.artifact.format são validados durante o empacotamento, então um artefato malformado falha aqui em vez de falhar em um consumidor. Veja Artefatos de build.

wippy publish

Publicar módulo no hub.

wippy publish
wippy publish --version 1.0.0
wippy publish --dry-run

Lê a partir do wippy.yaml no diretório atual.

O tipo do módulo normalmente é declarado como type: no wippy.yaml (veja Publicação); --module-type o sobrescreve para uma única publicação. Quando nenhum dos dois está definido, módulos recém-criados assumem application com um aviso de obsolescência.

wippy search

Buscar módulos no hub.

A busca usa, quando disponível, o token de autenticação armazenado para o registry selecionado. Autentique-se com wippy auth login para buscar com sua identidade no registry; --registry seleciona as credenciais do registry usadas.

wippy search http
wippy search "sql driver" --limit 20
wippy search auth --json

wippy auth

Gerenciar autenticação no registry.

wippy auth login

wippy auth login
wippy auth login --token YOUR_TOKEN

wippy auth logout

wippy auth logout

wippy auth status

wippy auth status
wippy auth status --json

wippy readme

Obter o README de um módulo a partir do hub.

wippy readme wippy/terminal
wippy readme wippy/terminal@1.2.3
wippy readme --json wippy/terminal@latest

wippy registry

Consultar e inspecionar entradas do registry. Ambos os subcomandos aceitam --profile e --set para moldar a configuração de runtime mesclada sob a qual as entradas são carregadas.

wippy registry list

wippy registry list
wippy registry list --kind "function.lua.*"
wippy registry list --ns "app.*" --json
wippy registry list --meta "type=api" --meta "enabled=true"

Operadores de metadados para --meta:

wippy registry show

wippy registry show app:http:handler
wippy registry show app:config --yaml

wippy version

Imprimir informações de versão.

wippy version
wippy version --short

Comandos Personalizados

Qualquer entrada process.lua ou process.wasm pode ser registrada como um comando nomeado adicionando metadados de command:

entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
        security:
          actor:
            id: app:migrations
          policies:
            - app.security:migrations
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main
    modules:
      - io
      - registry
      - funcs

Execute com:

wippy run migrate

Liste todos os comandos disponíveis:

wippy run list

wippy run list aceita --profile e --set para que a listagem reflita a mesma configuração de runtime mesclada que wippy run usaria.

Campos de Metadados do Comando

Qualquer tipo de entrada de processo funciona (process.lua, process.wasm). Nomes de comando não são verificados quanto à unicidade; quando várias entradas carregadas declaram o mesmo nome, a primeira correspondência na ordem do registry executa. Argumentos após o nome do comando são passados para o processo como payloads de string.

Segurança de comandos

Uma entrada de comando declara o ator e o escopo de políticas sob os quais seu lançamento pela CLI executa:

entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Executar migrações de banco de dados
        security:
          actor:
            id: system.migrations
            meta:
              role: operator
          policies:
            - app.security:migrations_policy
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main

O bloco fica dentro de meta.command porque se aplica apenas ao caminho de lançamento pela CLI — o operador iniciou o comando em seu próprio deployment, que é a âncora de confiança. Ele não tem efeito sobre spawns comuns da mesma entrada de processo; esses seguem o bloco security: da própria entrada.

A declaração é fail-closed e validada antes de o processo iniciar:

• Campos desconhecidos dentro de security são rejeitados.
• Um bloco security vazio (sem ator, sem políticas, sem grupos) é rejeitado.
• security sem um name é rejeitado — um comando precisa ser nomeável para ser lançado.
• Uma política ou grupo que não pode ser resolvido recusa o lançamento; a resolução é atômica, então um escopo parcial nunca é instalado.

Quando o bloco omite actor, o ator do chamador é herdado. Quando omite tanto policies quanto groups, o escopo do chamador é herdado.

Exemplos

Fluxo de Desenvolvimento

# Initialize dependency lock metadata
wippy init
wippy add wippy/test
wippy add wippy/llm
wippy install

# Check for errors
wippy lint

# Run with debug output
wippy run -c -v

# Override config for local dev
wippy run -o app:db:host=localhost -o app:db:port=5432

Deploy em Produção

# Create release pack with bytecode
wippy pack release.wapp --bytecode "**" --exclude-ns "test.**"

# Run from pack with memory limit
wippy run release.wapp -m 2G

Depuração

# Execute single process
wippy run --exec app:worker

# With profiler enabled
wippy run -p -v
# Then: go tool pprof http://localhost:6060/debug/pprof/heap

Gerenciamento de Dependências

# Add new dependency
wippy add acme/http@latest

# Force re-download
wippy install --force

# Update specific module
wippy update acme/http

Publicação

# Login to hub
wippy auth login

# Validate module
wippy publish --dry-run

# Publish
wippy publish --version 1.0.0 --release-notes "Initial release"

Variáveis de Ambiente

Valores no .wippy.yaml podem referenciar variáveis de ambiente do SO com ${env:NAME}, resolvidas no carregamento do arquivo; uma variável ausente falha o carregamento da configuração. Referências ${name} simples resolvem a partir da seção vars: da configuração.

Arquivo de Configuração

Crie .wippy.yaml para configurações persistentes:

logger:
  encoding: console

logmanager:
  stream_to_events: true

profiler:
  enabled: true
  address: localhost:6060

override:
  app:gateway:addr: ":9090"
  app:db:host: "localhost"

Veja Também

• Configuração - Referência do arquivo de configuração
• Observabilidade - Monitoramento e logging