CLI-Referenz

Verwenden Sie die Wippy-CLI, um Projekte zu initialisieren, die Runtime auszuführen, Abhängigkeiten zu verwalten, Registry-Einträge zu untersuchen und Module zu veröffentlichen.

Dies ist eine Befehlsreferenz. Beispiele zu Quellcode, Lock-Datei, Registry-Einträgen oder Veröffentlichungsmetadaten setzen ein bestehendes Projekt beziehungsweise Modul voraus und bilden kein einzelnes End-to-End-Projekt.

Globale Flags

Verfügbar bei allen Befehlen:

Die Reihenfolge für das Speicherlimit ist --memory-limit, dann GOMEMLIMIT, dann der Standard von 1 GB.

Die globale Option --config kann mehrfach übergeben werden, um Konfigurationsdateien zu komponieren. Dateien werden von links nach rechts zusammengeführt. Jede explizit benannte Datei muss existieren; ohne --config ist .wippy.yaml optional. Die erste Datei verankert relative Pfade. Danach werden --profile-Overlays und zuletzt --set-Überschreibungen angewendet. Siehe Konfiguration.

wippy publish überschattet die globale Option mit dem befehlsspezifischen --config <dir>. Dort ist der Wert das Verzeichnis mit wippy.yaml, nicht eine wiederholbare Runtime-Konfigurationsdatei.

wippy init

wippy.lock erstellen oder die Einstellungen für Quell- und Modulverzeichnis aktualisieren. Der Befehl legt weder Anwendungsquellcode noch Registry-Einträge an.

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

wippy run

Die Runtime starten oder einen Befehl ausführen.

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

Das Ausführen eines Hub-Moduls (wippy run org/module) löst es einmal auf, hält es in wippy.lock fest und legt die verifizierten Packs lokal ab. Nachfolgende Läufe derselben Referenz starten aus dem Lock — ohne Netzwerkzugriff. Ein Versions-Selektor, der nicht mehr zum Lock passt, wird mit dem Hinweis abgelehnt, wippy update auszuführen.

Bei einer lokalen Anwendung repariert wippy run einen veralteten Lock, bevor irgendein Runtime-Dienst startet. Es lädt die Abhängigkeitsdeklarationen aus den Quellen, und wenn der Lock sie bereits erfüllt, löst es den Graphen ausschließlich aus lokalen und installierten Belegen erneut auf (verifiziert-offline, ohne Netzwerkzugriff). Stimmt diese Offline-Auflösung mit dem Lock überein, läuft der Boot unverändert weiter. Gelingt sie, weicht aber ab, wird sie zum Kandidaten-Graphen; der Hub wird nur dann um Auflösung gebeten, wenn der Offline-Durchlauf scheitert oder der Lock die Quelldeklarationen nicht mehr erfüllt. Packs, die dem Kandidaten-Graphen fehlen, werden heruntergeladen und verifiziert, und erst dann wird wippy.lock neu geschrieben. Ein Lock, der eine Deployment-Wurzel auswählt, ist maßgeblich und wird nie erneut aufgelöst.

--exec blockiert, bis der gestartete Prozess sein Ergebnis liefert, und gibt dann den Exit-Code des Prozesses als Exit-Code der CLI weiter. Strg-C während --exec bricht den laufenden Prozess ab, und die Runtime fährt trotzdem sauber herunter; ein zweites Signal erzwingt den sofortigen Abbruch.

--set schreibt jeden Laufzeit-Konfigurationswert über die Befehlszeile, pro Blatt über .wippy.yaml zusammengeführt:

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

Werte werden nach Form konvertiert: true/false zu Bool, Ganz- und Gleitkommazahlen zu Zahlen, alles andere bleibt ein String (Zeitdauern wie 5s werden geparst, wo die Option eine erwartet).

wippy test

Den Test-Entrypoint ausführen: den Prozess-Entry, der den Use Case test deklariert. Die Runtime bootet, führt diesen Entry aus und beendet sich. wippy run führt Test-Entrypoints nicht automatisch aus; Testen läuft immer über 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

Lua-Code auf Typfehler und Warnungen prüfen.

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

Validiert quellcodehaltige Einträge der Kinds function.lua, library.lua, process.lua und workflow.lua. Vorkompilierte .bc-Einträge enthalten keinen parsbaren Quellcode und werden übersprungen.

wippy add

Eine Modulabhängigkeit hinzufügen.

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

wippy install

Abhängigkeiten aus der Lock-Datei installieren.

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

wippy update

Abhängigkeiten aktualisieren und Lock-Datei neu generieren.

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

wippy artifacts

Mit Build-Zeit-Dateisystem-Artefakten arbeiten.

wippy artifacts materialize

Ein Artefakt-Dateisystem aus einem vorhandenen Pack validieren und materialisieren.

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

Die Ressource wird über ihren vollständigen namespace:name adressiert, muss meta.artifact.format deklarieren, und dieses Format muss in der CLI registriert sein. Der Befehl löst keine Modulabhängigkeiten auf, verändert wippy.lock nicht, ruft keine Paketmanager auf und nimmt an der Runtime-Komposition nicht teil. Siehe Build-Zeit-Artefakte.

wippy pack

Ein Snapshot-Pack (.wapp-Datei) erstellen.

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

Ohne --embed oder --embed-all greifen die Embed-Muster auf den embed:-Abschnitt des Modul-Manifests wippy.yaml zurück. Das Packen einer Anwendung übernimmt auch eingebettete Ressourcen aus ihren Abhängigkeits-Packs, und nur die Befehle des Hauptmoduls werden vom resultierenden Pack bereitgestellt.

Die Ausgabedatei wird atomar geschrieben: Das Pack wird in eine temporäre Datei im Zielverzeichnis gebaut, synchronisiert, verifiziert und erst dann über das Ziel umbenannt, wobei es die Berechtigungen einer vorhandenen Datei übernimmt. Ein fehlgeschlagener Pack-Lauf lässt die vorherige Datei unangetastet. Eine Ausgabe zu benennen, die zugleich eine der Eingaben des Packs ist — derselbe Pfad oder ein Hard- bzw. Symlink, der auf dieselbe Datei zeigt — wird abgelehnt, statt die Eingabe mitten im Lesen abzuschneiden.

--meta kann keine reservierten Metadaten schreiben. Der Schlüssel registry sowie alles unter den Präfixen wippy. oder system. gehört dem Pack-Format und wird abgelehnt.

Ressourcen, die meta.artifact.format deklarieren, werden beim Packen validiert, sodass ein fehlerhaftes Artefakt hier scheitert und nicht erst beim Konsumenten. Siehe Build-Zeit-Artefakte.

wippy publish

Modul im Hub veröffentlichen.

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

Liest aus wippy.yaml im aktuellen Verzeichnis.

Der Modultyp wird normalerweise als type: in wippy.yaml deklariert (siehe Veröffentlichen); --module-type überschreibt ihn für eine einzelne Veröffentlichung. Ist keiner der Werte gesetzt, erhalten neu erstellte Module standardmäßig den Typ application mit einer Deprecation-Warnung.

wippy search

Module im Hub suchen.

Die Suche verwendet, sofern vorhanden, das gespeicherte Authentifizierungstoken der ausgewählten Registry. Mit wippy auth login suchen Sie mit Ihrer Registry-Identität; --registry bestimmt, welche Zugangsdaten verwendet werden.

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

wippy auth

Registry-Authentifizierung verwalten.

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

README eines Moduls aus dem Hub abrufen.

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

wippy registry

Registry-Einträge abfragen und inspizieren. Beide Unterbefehle akzeptieren --profile und --set, um die zusammengeführte Runtime-Konfiguration zu formen, unter der die Einträge geladen werden.

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"

Metadaten-Operatoren für --meta:

wippy registry show

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

wippy version

Versionsinformationen ausgeben.

wippy version
wippy version --short

Benutzerdefinierte Befehle

Jeder process.lua- oder process.wasm-Entry kann als benannter Befehl registriert werden, indem command-Metadaten hinzugefügt werden:

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

Ausführen mit:

wippy run migrate

Alle verfügbaren Befehle auflisten:

wippy run list

wippy run list akzeptiert --profile und --set, sodass die Auflistung dieselbe zusammengeführte Laufzeitkonfiguration widerspiegelt, die wippy run verwenden würde.

Befehl-Metadatenfelder

Jede Art von Prozess-Entry funktioniert (process.lua, process.wasm). Befehlsnamen werden nicht auf Eindeutigkeit geprüft; deklarieren mehrere geladene Entries denselben Namen, läuft der erste Treffer in Registry-Reihenfolge. Argumente nach dem Befehlsnamen werden als String-Payloads an den Prozess übergeben.

Befehlssicherheit

Ein Befehls-Entry deklariert den Actor und den Policy-Scope, unter dem sein CLI-Start läuft:

entries:
  - name: migrate_runner
    kind: process.lua
    meta:
      command:
        name: migrate
        short: Run database migrations
        security:
          actor:
            id: system.migrations
            meta:
              role: operator
          policies:
            - app.security:migrations_policy
          groups:
            - app.security:operators
    source: file://runner.lua
    method: main

Der Block steht innerhalb von meta.command, weil er nur für den CLI-Startpfad gilt — der Operator hat den Befehl auf seinem eigenen Deployment gestartet, und das ist der Vertrauensanker. Auf gewöhnliche Spawns desselben Prozess-Entries hat er keine Wirkung; diese folgen dem eigenen security:-Block des Entries.

Die Deklaration ist fail-closed und wird validiert, bevor der Prozess startet:

• Unbekannte Felder innerhalb von security werden abgelehnt.
• Ein leerer security-Block (kein Actor, keine Policies, keine Gruppen) wird abgelehnt.
• security ohne name wird abgelehnt — ein Befehl muss benennbar sein, um gestartet werden zu können.
• Eine Policy oder Gruppe, die nicht aufgelöst werden kann, verweigert den Start; die Auflösung ist atomar, sodass nie ein unvollständiger Scope installiert wird.

Lässt der Block actor weg, wird der Actor des Aufrufers geerbt. Lässt er sowohl policies als auch groups weg, wird der Scope des Aufrufers geerbt.

Beispiele

Entwicklungs-Workflow

# 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

Produktions-Deployment

# 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

Debugging

# 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

Abhängigkeitsverwaltung

# Add new dependency
wippy add acme/http@latest

# Force re-download
wippy install --force

# Update specific module
wippy update acme/http

Veröffentlichung

# Login to hub
wippy auth login

# Validate module
wippy publish --dry-run

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

Umgebungsvariablen

Werte in .wippy.yaml können OS-Umgebungsvariablen mit ${env:NAME} referenzieren, aufgelöst beim Laden der Datei; eine fehlende Variable lässt das Laden der Konfiguration fehlschlagen. Nackte ${name}-Referenzen werden stattdessen aus dem vars:-Abschnitt der Konfiguration aufgelöst.

Konfigurationsdatei

.wippy.yaml für persistente Einstellungen erstellen:

logger:
  encoding: console

logmanager:
  stream_to_events: true

profiler:
  enabled: true
  address: localhost:6060

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

Siehe auch

• Konfiguration — Referenz der Konfigurationsdatei
• Observability — Monitoring und Logging