CLI-Referenz

Bei laufendem Cuby lassen sich Produkte auch im Terminal verwalten — installieren, aktualisieren, starten, stoppen, Status und Logs abfragen. Damit sind Installationen auch auf Servern ohne Browser und in Skripten möglich.

Die CLI arbeitet ausschließlich über die REST API eines laufenden Cuby. Lokal und remote ist es derselbe Codepfad: Nur der Cuby-Prozess verändert Produkte, die CLI ist ein Client.

Aufruf

cuby                    # ohne Kommando: startet den Cuby-Server
cuby list               # mit Kommando: führt die CLI aus und beendet sich
cuby --help             # alle Kommandos und Optionen

Das erste Argument, das einem bekannten Kommando entspricht, startet die CLI — alles davor gehört zum Server-Aufruf.

Kommandos

install, update, uninstall, start, stop und restart nehmen mehrere Produkte in einem Aufruf entgegen.

Optionen

Optionen werden als --option wert oder --option=wert geschrieben. Eine unbekannte Option bricht den Aufruf mit Exit-Code 2 ab.

Instanz-IDs und Aliase

Ein Produkt kann mehrfach installiert werden. Beim Installieren wird der Alias mit @ angehängt, alle weiteren Kommandos arbeiten mit der daraus entstandenen Instanz-ID:

cuby install processcube-lokal@test    # Instanz-ID: processcube-lokal__test
cuby restart processcube-lokal__test

Ohne Alias sind Produkt-ID und Instanz-ID identisch. cuby list zeigt die Instanz-IDs, cuby list --available die Produkt-IDs aus dem Marketplace.

API Key

Der API Key ist optional. Die CLI löst ihn in dieser Reihenfolge auf:

1. --api-key <key>
2. Umgebungsvariable CUBY_API_KEY
3. Umgebungsvariable PROCESSCUBE_API_KEY
4. API Key des lokalen Cuby aus dem Secret Store

Für den lokalen Cuby genügt damit der Aufruf ohne weitere Angabe. Ein abgelehnter Key führt zu einer 401-Meldung mit Hinweis auf --api-key. Details unter Authentifizierung.

Anderen Cuby ansteuern

Mit --url richtet sich jedes Kommando an eine andere Cuby-Instanz — praktisch für Server- und Cloud-Installationen:

cuby list --url https://cuby.example.com --api-key $CUBY_API_KEY
cuby install processcube-k8s --url https://cuby.example.com

Fehlt das Protokoll, wird http:// ergänzt.

Fortschritt und Warten

install und update starten den Vorgang und warten standardmäßig auf den Abschluss. Der Fortschritt wird im Terminal ausgegeben, der Status alle 500 ms abgefragt; nach 30 Minuten bricht die CLI mit einer Zeitüberschreitung ab. Der Vorgang selbst läuft im Cuby weiter.

Mit --no-wait wird der Vorgang nur angestoßen:

cuby install processcube-lokal --no-wait

Plugin-Dialoge vorab beantworten

Fragt ein Produkt während der Installation per cuby.prompt() nach Eingaben, blockiert der Vorgang bis eine Antwort vorliegt. Mit --answers werden die Antworten vorab übergeben — als JSON-Array oder als Pfad zu einer JSON-Datei, ein Eintrag pro Dialog in der Reihenfolge des Auftretens:

cuby install mein-produkt --answers '[{"region":"eu"},{"token":"abc123"}]'
cuby install mein-produkt --answers antworten.json

Die CLI hängt sich dafür mit demselben Vertrag wie das Frontend an die Socket.IO-Events des Servers.

Ausgabe

Ohne --json gibt die CLI Tabellen aus:

$ cuby list
INSTANCE-ID            NAME               VERSION  STATUS
─────────────────────  ─────────────────  ───────  ───────
processcube-lokal      ProcessCube Lokal  0.6.0    ok
processcube-lokal__qa  ProcessCube Lokal  0.6.0    stopped

Der Status fasst den Prozesszustand und den Health-Check des Produkts zusammen: ok bzw. fehlerhaft kommen aus der Rückmeldung des Produkts selbst (z.B. „Alle Services laufen”, „Nicht erreichbar”), sonst wird der Prozessstatus (running, stopped) bzw. unbekannt angezeigt. Plugin-Produkte laufen nicht als Kindprozess — ihr Laufzeit-Signal ist die /health-Route des Plugins, dieselbe Quelle wie im Dashboard.

Mit --json liefern alle Kommandos maschinenlesbare Ausgaben inklusive Prozess- und Health-Details:

cuby list --json | jq -r '.[] | select(.status != "ok") | .instanceId'

Logs

cuby logs processcube-lokal                 # letzte 100 Zeilen aus dem Speicher
cuby logs processcube-lokal --lines 500     # mehr Zeilen
cuby logs processcube-lokal --file          # aus der Log-Datei statt aus dem Speicher

Zeilen aus stderr werden mit [ERROR] gekennzeichnet. Details zu den beiden Log-Quellen unter Produktverwaltung.

Exit-Codes

Damit lässt sich die Einrichtung automatisieren:

#!/usr/bin/env bash
set -e
 
cuby install processcube-lokal --answers antworten.json
cuby status --json > status.json

Weiterführend

• API-Referenz — die Endpunkte, die die CLI verwendet
• Produktverwaltung — dieselben Vorgänge in der Weboberfläche
• Troubleshooting