nucli für Administration

nucli ist das Kommandozeilenwerkzeug für Workspace. Administratoren und Betreiber nutzen es für Login, Statusabfragen, Diagnose, Ressourcenlisten und kontrollierte API-Aufrufe.

Installation

Installieren Sie nucli aus dem passenden Linux-Release-Artefakt:

text

https://git.schukai.me/releases/nucleus-cli/releases

Laden Sie manifest.txt, SHA256SUMS und compatibility.json aus demselben Release herunter. compatibility.json nennt die CLI-Version, den unterstützten API-Major und die Fähigkeiten, die nucli für Login und optionale Abläufe erwartet.

Release-Archiv installieren

Das Archiv enthält ein einzelnes Binary. Installieren Sie es in ein Verzeichnis, das in Ihrem PATH liegt:

bash

tar -xzf nucli-<version>-linux-amd64.tar.gz
sudo install -d -m 0755 /usr/local/bin
sudo install -m 0755 nucli-<version>-linux-amd64/nucli /usr/local/bin/nucli
nucli version

Wenn /usr/local/bin nicht existiert, legt install -d das Verzeichnis an. Wenn Sie keinen sudo-Zugriff haben oder nucli nur für Ihren Benutzer installieren möchten, verwenden Sie ~/.local/bin:

bash

mkdir -p "$HOME/.local/bin"
install -m 0755 nucli-<version>-linux-amd64/nucli "$HOME/.local/bin/nucli"
printf '\nexport PATH="$HOME/.local/bin:$PATH"\n' >> "$HOME/.profile"
. "$HOME/.profile"
command -v nucli
nucli version

Öffnen Sie ein neues Terminal, wenn Ihre Shell .profile nicht für die laufende Sitzung lädt.

Linux-Paket installieren

Wenn Sie ein Linux-Paket verwenden, installieren Sie das Paket für Ihre Distribution:

bash

sudo apt install ./nucli_<version>-1_amd64.deb

bash

sudo rpm -Uvh nucli-<version>-1.x86_64.rpm

Prüfen Sie danach:

bash

nucli version
nucli --help

Konfigurationsverzeichnis

nucli nutzt genau ein lokales Konfigurationsverzeichnis. Wenn Sie keinen Pfad angeben, wählt nucli den User-Config-Standard des Betriebssystems. Auf Linux ist das $XDG_CONFIG_HOME/nucli; wenn XDG_CONFIG_HOME nicht gesetzt ist, nutzt nucli $HOME/.config/nucli.

Die Reihenfolge ist:

Vorrang	Einstellung	Wirkung
1	`--config-dir <verzeichnis>`	Gilt nur für diesen Befehl.
2	`NUCLI_CONFIG_DIR=<verzeichnis>`	Gilt für die Shell, den Container oder das Skript.
3	User-Config-Default	Nutzt auf Linux `$XDG_CONFIG_HOME/nucli` oder `$HOME/.config/nucli`.

Verwenden Sie --config-dir, nicht --config. nucli erwartet ein Verzeichnis und legt darin config.json an. Diese Datei enthält lokale Profil-Metadaten wie Host, Profilname und Session-Ablauf, aber keine Passwörter.

Der Pfad muss lesbar sein. Schreibende Befehle wie login, logout oder profiles use müssen das Verzeichnis auch anlegen oder beschreiben dürfen. Für Container, CI-Jobs und kurzlebige Shells ist NUCLI_CONFIG_DIR oft praktischer als ein wiederholtes --config-dir:

bash

export NUCLI_CONFIG_DIR="$PWD/.nucli"
mkdir -p "$NUCLI_CONFIG_DIR"
nucli --host https://workspace.example.com login --email <email>

nucli login speichert Session-Tokens getrennt von config.json. Auf Linux nutzt nucli secret-tool, wenn es verfügbar ist. Wenn kein Secret Service vorhanden ist und Sie NUCLI_STORE_KEY setzen, schreibt nucli verschlüsselte Token-Dateien unter <config-dir>/tokens/.

Nutzung in der Docker-Demo

Wenn Sie Workspace mit der Docker-Demo gestartet haben, können Sie nucli auch im laufenden Workspace-Container verwenden:

bash

docker compose exec nucleus nucli --help
docker compose exec nucleus nucli --host https://localhost:8443 discovery

Wenn Sie für die lokale Demo ein eigenes Zertifikat gemountet haben und nucli der ausstellenden Stelle noch nicht vertraut, übergeben Sie die lokale CA als Trust Anchor:

bash

docker compose exec nucleus sh -lc 'SSL_CERT_FILE=/certs/local-dev-ca.crt nucli --host https://localhost:8443 discovery'

Der Pfad hinter SSL_CERT_FILE ist ein Container-Pfad. Er muss zu dem Zertifikats-Mount in Ihrer Compose-Datei passen. Verwenden Sie hier die ausstellende CA, nicht das einzelne Serverzertifikat.

In schlanken Containern oder kurzlebigen Shells muss nucli außerdem in ein beschreibbares Konfigurationsverzeichnis schreiben können, sobald Sie sich anmelden:

bash

export NUCLI_DEMO_STORE_KEY="$(openssl rand -base64 32)"
docker compose exec -e NUCLI_STORE_KEY="$NUCLI_DEMO_STORE_KEY" nucleus \
  sh -lc 'mkdir -p /tmp/nucli && NUCLI_CONFIG_DIR=/tmp/nucli SSL_CERT_FILE=/certs/local-dev-ca.crt nucli --host https://localhost:8443 login --email <email>'

Ersetzen Sie https://localhost:8443, wenn Ihr lokales Zertifikat einen anderen Hostnamen abdeckt.

nucli login braucht einen persistenten Token-Store. Auf Linux nutzt nucli secret-tool, wenn es verfügbar ist. In Containern ohne Secret Service setzen Sie für die lokale Demo NUCLI_STORE_KEY und verwenden ein beschreibbares --config-dir oder NUCLI_CONFIG_DIR; der Schlüssel schützt die verschlüsselte lokale Token-Datei und gehört nicht in Compose-Dateien, Repositories oder Shell-Historien für produktive Umgebungen. Verwenden Sie denselben NUCLI_STORE_KEY erneut, wenn Sie später mit demselben Konfigurationsverzeichnis weiterarbeiten.

Wenn Sie nucli direkt auf dem Host gegen die lokale Demo ausführen, verwenden Sie ebenfalls einen beschreibbaren Pfad:

bash

mkdir -p "$PWD/.nucli"
export SSL_CERT_FILE="$PWD/certs/local-dev-ca.crt"
export NUCLI_STORE_KEY="$(openssl rand -base64 32)"
export NUCLI_CONFIG_DIR="$PWD/.nucli"
nucli --host https://localhost:8443 login --email <email>

Anmelden

nucli spricht immer mit einer laufenden Workspace-Instanz. Die wichtigsten Begriffe:

Begriff	Bedeutung
Host / Workspace-URL	Basisadresse der Workspace-Instanz, zum Beispiel `https://workspace.example.com`.
Profil	Lokaler `nucli`-Eintrag mit Host, Session-Metadaten und Token-Verweis.
Tenant-Alias	Lesbarer lokaler Profilname für einen Mandanten, zum Beispiel `mandant-a`. Der Alias existiert nur auf Ihrem Rechner.
Tenant / Mandant	Technischer und organisatorischer Datenkontext eines Arbeitsbereichs. Fachliche Daten gehören immer zu einem konkreten Mandanten.
Tenant-ID	Serverseitige UUID des Mandanten. Nutzen Sie sie in Skripten als Schutz gegen den falschen aktiven Mandanten.
Aktiver Tenant	Der Mandant, an den die gespeicherte Session gebunden ist. `nucli` wechselt ihn bei API-Aufrufen nicht automatisch.

Melden Sie sich zunächst an:

bash

nucli --host <workspace-url> login --email <email>
nucli whoami

nucli speichert die Sitzung lokal und verwendet sie für spätere Befehle. Melden Sie sich ab, wenn Sie die Sitzung nicht mehr benötigen:

bash

nucli logout

Wenn Ihr Benutzer mehreren Mandanten zugeordnet ist, fragt nucli login im interaktiven Terminal nach dem Zielmandanten. Für Skripte übergeben Sie die Tenant-ID direkt:

bash

printf '%s\n' "$NUCLEUS_PASSWORD" \
  | nucli --tenant mandant-a \
      --host https://workspace.example.com \
      --tenant-id 11111111-1111-1111-1111-111111111111 \
      login --email admin@example.com --password-stdin

Der Wert hinter --tenant ist frei wählbar und bleibt lokal. Verwenden Sie sprechende Aliase wie prod-shop, stage-shop oder system.

Tenant-ID finden

Nutzen Sie nach dem Login whoami:

bash

nucli --tenant mandant-a whoami
nucli --tenant mandant-a whoami --json

Die Ausgabe enthält die aktive Tenant-ID. Lokal gespeicherte Profile zeigen die ID ebenfalls:

bash

nucli profiles
nucli profiles --json

Wenn Sie noch keine ID kennen, melden Sie sich interaktiv mit einem neuen Alias an und lesen Sie die ID danach aus:

bash

nucli --tenant mandant-a --host https://workspace.example.com login --email admin@example.com
nucli --tenant mandant-a whoami --json

Mit Systemrechten finden Sie Mandanten außerdem in der Oberfläche unter System > Mandanten. Öffnen Sie den Mandanten und verwenden Sie das Feld Id als Tenant-ID.

Status und Diagnose

Prüfen Sie vor administrativen Aufrufen zuerst den Kontext:

bash

nucli --tenant mandant-a whoami
nucli --tenant mandant-a --tenant-id 11111111-1111-1111-1111-111111111111 doctor
nucli --tenant mandant-a scopes

Die Diagnosebefehle haben unterschiedliche Aufgaben:

Befehl	Zweck
`nucli status`	Zeigt lokale Profil- und Session-Metadaten.
`nucli whoami`	Prüft die gespeicherte Session am Server und zeigt Profil, Host, Tenant-Alias und aktive Tenant-ID.
`nucli scopes`	Zeigt die vom Server gemeldeten Berechtigungen der aktuellen Session.
`nucli doctor`	Prüft lokales Profil, Host, Tokenstore, Session, Tenant-Guard und öffentliche Discovery.
`nucli diagnose`	Ruft die tenantgebundene Diagnose-API ab und zeigt kuratierte Status- und Zählwerte.
`nucli readiness`	Prüft systemweite Betriebsbereitschaft im System-Mandanten.

Beispiele:

bash

nucli --tenant mandant-a diagnose
nucli --tenant mandant-a diagnose --json
nucli diagnose --all-tenants
nucli --tenant system readiness summary

diagnose --all-tenants prüft nur lokal konfigurierte Profile mit gespeicherter Session. Es ruft keine serverseitige Liste aller Mandanten ab.

Weitere Diagnoseabläufe finden Sie unter Diagnose und Readiness.

Mandantenkontext

Viele Befehle brauchen einen Mandantenkontext:

bash

nucli --tenant <tenant> resources list
nucli --tenant <tenant> sites list

Bei mehreren Mandanten schützen Sie Skripte zusätzlich mit der erwarteten Tenant-ID:

bash

nucli --tenant <tenant> --tenant-id <tenant-id> whoami

--tenant wählt das lokale Profil. --tenant-id prüft, ob dieses Profil wirklich mit der erwarteten serverseitigen Tenant-ID angemeldet ist. Wenn die IDs nicht übereinstimmen, bricht nucli ab. Der Guard schützt Skripte, schaltet aber keinen Mandanten um.

Nutzen Sie --tenant system nur für ausdrücklich systemweite Befehle, zum Beispiel Readiness oder Operator-Diagnose. Der System-Mandant ist kein Arbeitsmandant für fachliche Ressourcen. Verwenden Sie für Ressourcen, Sites, Import-Jobs oder fachliche API-Aufrufe den jeweiligen Arbeitsmandanten.

Sites verwalten

Nutzen Sie nucli für wiederholbare Site-Manager-Abläufe: Status prüfen, Dev-Mode starten, Dateien senden, Builds erzeugen und Releases veröffentlichen.

bash

nucli --tenant <tenant> sites list
nucli --tenant <tenant> sites init <site-id>
nucli --tenant <tenant> sites init <site-id> --release
nucli --tenant <tenant> sites workspace <site-id>
nucli --tenant <tenant> sites structure <site-id>
nucli --tenant <tenant> sites readiness <site-id>
nucli --tenant <tenant> sites validate <site-id>

sites list zeigt die Site-ID als id. Nutzen Sie diese ID als <site-id> für skriptbare Befehle. sites init initialisiert eine neu angelegte, noch leere Site mit Projektstruktur und Default-Page. Ohne --release entsteht kein aktiver Live-Release. Ergänzen Sie --release, wenn die Default-Page direkt als erster statischer Release veröffentlicht werden soll. Führen Sie den Befehl nicht auf Sites mit bestehenden Projektdateien erneut aus.

Für Bearbeitung und Vorschau starten Sie eine Dev-Session. Erzeugen Sie danach einen Vorschau-Link passend zum Reviewer. Wenn Ihr Team Freigabelink sagt, ist bei Sites dieser Vorschau-Link gemeint:

bash

nucli --tenant <tenant> sites dev start <site-id> --review-window 7d
nucli --tenant <tenant> sites preview link <site-id> --mode dev --path / --consumer authenticated --open
nucli --tenant <tenant> sites preview link <site-id> --mode dev --path /oeffentlich --consumer anonymous

Nutzen Sie --consumer anonymous für Reviewer ohne Login und nur für öffentliche Pfade aus sites workspace unter previewHandoff.publicTargets. Nutzen Sie --consumer authenticated, wenn der Zielbrowser sich für geschützte Seiten normal anmelden soll. --mode dev öffnet den Dev-Mode-Stand der Site; hängen Sie ?mode=dev nicht manuell an öffentliche Site-URLs an. Ein Vorschau-Link schaltet nur den Quellstand um; er erweitert keine Seitenrechte und veröffentlicht nichts.

Wenn Sie viele Site-Dateien mit einem lokalen Editor bearbeiten möchten, mounten Sie die Projektquellen im Dev-Mode:

bash

nucli --tenant <tenant> sites dev mount <site-id> --dry-run
nucli --tenant <tenant> sites dev mount <site-id>
nucli --tenant <tenant> sites dev mount

dev mount startet oder verlängert die Dev-Session, prüft lokal sshfs, fragt vor dem Mount nach Bestätigung und zeigt danach den lokalen Site-Pfad. Wenn Sie keine Site-ID angeben, zeigt nucli im interaktiven Terminal eine nummerierte Site-Liste. Der Befehl bearbeitet keine gefrorenen Releases und veröffentlicht nichts.

Installieren Sie sshfs auf dem Rechner, auf dem Sie nucli sites dev mount ausführen. Unter Debian/Ubuntu reicht zum Beispiel sudo apt install sshfs, unter macOS benötigen Sie macFUSE und sshfs. In nicht interaktiven Umgebungen nutzen Sie zuerst --dry-run, um Session, Pfade und den geplanten sshfs-Befehl zu prüfen.

Dateien können Sie kontrolliert lesen, schreiben oder als Patchset anwenden:

bash

nucli --tenant <tenant> sites files tree <site-id>
nucli --tenant <tenant> sites files get <site-id> pages/index.de.yaml
nucli --tenant <tenant> sites files put <site-id> pages/index.de.yaml --input index.de.yaml --if-match <etag>
nucli --tenant <tenant> sites files apply <site-id> --input patchset.json

Wenn Sie nur die SFTP-Verbindungsdaten benötigen, liefert mount-info die passende Verbindung:

bash

nucli --tenant <tenant> sites mount-info <site-id>

Nach der Initialisierung bleiben Build und Veröffentlichung getrennt:

bash

nucli --tenant <tenant> sites build <site-id> --wait
nucli --tenant <tenant> sites publish <site-id> --release <release-id>

Veröffentlichen Sie erst, wenn validate erfolgreich war, der Build eine konkrete Release-ID geliefert hat und die Freigabe genau für diese Release-ID vorliegt.

Erstellen Sie vor größeren Änderungen ein Backup und prüfen Sie Restore-Archive zuerst als Plan:

bash

nucli --tenant <tenant> sites backup <site-id> --output site-backup.zip
nucli --tenant <tenant> sites restore <site-id> --input site-backup.zip
nucli --tenant <tenant> sites restore <site-id> --input site-backup.zip --apply

Die vollständige Site-Manager-Anleitung finden Sie unter Sites und CMS.

Sichere Ausgabe

Für Supportfälle und Protokolle können Sie Ausgaben zusammenfassen oder sensible Werte entfernen:

bash

nucli api GET /api/v1/meta/discovery --summary
nucli api GET /api/v1/meta/privacy --redact

Nutzen Sie --save, wenn Sie Antworten kontrolliert in eine Datei schreiben wollen:

bash

nucli api GET /api/v1/meta/privacy --redact --save privacy-redacted.json

Für providerbezogene Konfigurationen kann nucli api gezielt Admin-Endpunkte aufrufen. Das Beispiel für PayPal finden Sie unter PayPal einrichten.