nucli für Administration

nucli ist der tenantgebundene HTTP-Client für Workspace. Administratoren und Betreiber nutzen ihn für Login, Statusabfragen, Diagnose, Ressourcenlisten und kontrollierte API-Aufrufe gegen einen laufenden Server. Nach der Einrichtung zeigt nucli whoami das lokale Profil, den Host, den Tenant-Alias und die aktive Tenant-ID. Der Befehl prüft die gespeicherte Session, gibt aber keine Personen- oder Tokendaten aus.

Nutzen Sie numin nicht als Ersatz für nucli. numin besitzt keinen Remote-Login und umgeht keine Berechtigungen oder Mandantengrenzen eines laufenden Servers.

Installation

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

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.

Die hier dokumentierten öffentlichen Artefakte sind Linux-amd64-Artefakte. Wenn Sie Workspace lokal auf macOS oder Windows testen, können Sie nucli in der Docker-Demo im laufenden Workspace-Container verwenden oder eine freigegebene Linux-Umgebung nutzen.

Release-Archiv installieren

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

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:

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:

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

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

Prüfen Sie danach:

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:

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:

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:

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:

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:

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:

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:

Melden Sie sich zunächst an:

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:

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:

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:

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:

nucli profiles
nucli profiles --json

Agenten-Workflows anzeigen

nucli skills list zeigt kompakte Arbeitsanweisungen für automatisierte Agenten. Nutzen Sie nucli skills show operations, wenn ein Agent Diagnose, Findings, Taskstream-Job-Hygiene, Workflow-Owned-Repair oder Telemetrie-Fehlergruppen einordnen soll. Der Operations-Skill zeigt den sicheren Ablauf für Taskstream-Job-Hygiene: zuerst Summary und Preview lesen, danach nur vom Server als geeignet gemeldete Jobs archivieren und archivierte Jobs bei Bedarf wiederherstellen. Er grenzt außerdem serverseitige Arbeit mit nucli von ausdrücklich freigegebener lokaler Offline-Wartung mit numin ab. Nutzen Sie nucli skills show commerce-shipping, wenn ein Agent Versandkonfiguration, Lieferzusagen oder Lieferavise prüft. Der Skill trennt Kundenwunsch, Verkäuferplanung und Verkäuferzusage, liest Profile, Terminaggregate und die versionierte Avis-Historie und fordert für manuelle Versendungen oder Berichtigungen eine ausdrückliche Freigabe. E-Mail und PDF sind die verfügbaren Ausgabekanäle; DESADV/EDIFACT bleibt ein separater Partner-Adapter. Die fachliche Bedienung steht unter Liefertermine und Lieferavis verwalten. Nutzen Sie nucli skills show pim-product-maintenance, wenn ein Agent PIM-Produktpflege, Produktmedien, Veröffentlichung, Readiness und Bestandsübergabe einordnen soll. Nutzen Sie nucli skills show system-artifacts, wenn ein Agent globale Systemartefakt-Releases planen, nach ausdrücklicher Freigabe anwenden und den Lauf prüfen soll. Den vollständigen Ablauf erklärt Systemartefakt-Releases sicher anwenden.

nucli skills list
nucli skills show operations
nucli skills show commerce-shipping
nucli skills show pim-product-maintenance
nucli skills show system-artifacts

Wenn Ihr Agenten-Client MCP unterstützt, starten Sie nucli lokal als stdio-MCP-Server:

nucli --tenant mandant-a mcp serve

Der MCP-Server nutzt denselben Host, denselben Tenant-Guard und denselben Tokenstore wie andere nucli-Befehle. Er öffnet keinen HTTP-Port. Tools geben strukturierte Antworten zurück, aber keine Session-Tokens, Cookie-Werte oder Secret-Store-Details. Mutierende Tools verlangen eine ausdrückliche Freigabe im Tool-Aufruf; nucli ersetzt dadurch keine Nutzerentscheidung. Für Systemartefakte stehen Skill-, Status-, Plan-, Apply- und Run-Tools bereit. Das Apply-Tool verlangt approved: true; ohne diesen Wert sendet nucli keinen Apply-Request.

Der Operations-Workflow verweist auf den adapterbasierten Workflow-Owned-Repair. Aktuell ist product_variant unterstützt. Verwenden Sie den Repair nicht für telemetry_error_group, solange kein Telemetrie-Adapter freigegeben ist. Er beschreibt außerdem den sicheren read-before-write-Ablauf für die globale SMTP-Egress-Portpolicy: System-Tenant und Scopes prüfen, vorhandenen ConfigValue lesen, nur die vollständige Portliste schreiben und die installationsweite Wirkung vor der Mutation ausdrücklich freigeben. Den fachlichen Portvertrag und die konkreten Befehle erklärt Mail und Benachrichtigungen.

Ressourcen und API-Payloads entdecken

Nutzen Sie nucli resources, wenn ein Agent oder Skript nicht wissen soll, welche API-Pfade und Felder ein Ressourcentyp aktuell unterstützt. Lesen Sie zuerst die Server-Metadaten und erzeugen Sie danach den Payload:

nucli --tenant mandant-a resources list --json
nucli --tenant mandant-a resources meta pim.product-variants --save product-variants-meta.json
nucli --tenant mandant-a resources create pim.product-variants --input product-variant.json --summary

Für direkte API-Aufrufe übergeben Sie Request-Bodies mit --input <datei> oder --input -. nucli api hat keinen --body-Schalter:

printf '%s' '{"target_status":"ready","comment":"Freigabe vorbereiten"}' \
  | nucli --tenant mandant-a api POST /api/v1/pim/product-variants/<variant-id>/lifecycle/transition \
      -H 'X-Idempotency-Key: <stabiler-schluessel>' \
      --input -

Verwenden Sie vor mutierenden Befehlen immer whoami, doctor oder --tenant-id, wenn ein Skript den aktiven Mandanten eindeutig absichern muss.

Serverdeklarierte Guides nutzen

Nutzen Sie nucli guides, wenn ein Agent oder Skript einen geführten Arbeitsablauf braucht, ohne Produktlogik im Client zu hinterlegen:

nucli --tenant mandant-a guides list
nucli --tenant mandant-a guides show commerce.demo-shop.publication
nucli --tenant mandant-a guides check commerce.demo-shop.publication --input guide-context.json
nucli --tenant mandant-a guides run commerce.demo-shop.publication --dry-run --input guide-context.json

guides list und guides show lesen den serverseitigen Guide-Vertrag. guides check sendet nur den angegebenen Kontext an den Server. guides run führt nur mit --dry-run aus und gibt den serverdeklarierten Plan zurück. nucli führt dabei keine Guide-Schritte aus und entscheidet nicht, ob ein Produkt, Preis, Vertriebskanal, Lifecycle-Übergang oder Storefront-Status fachlich zulässig ist.

Ein Guide-Kontext ist ein JSON-Objekt. Die benötigten Felder stehen im Guide:

{
  "context": {
    "salesChannelId": "11111111-1111-1111-1111-111111111111",
    "localeCodes": ["de-DE", "en-US"],
    "productVariantIds": ["22222222-2222-2222-2222-222222222222"]
  }
}

Guides sind mandantengebunden und benötigen aktuell tenant_diagnostics:read. Tenant-spezifische Workflow-Definitionen, Transitions und fachliche Validierungen bleiben Serververträge. Wenn ein Guide einen mutierenden Schritt beschreibt, zeigt nucli ihn nur im Dry-Run an; ein mutierender Runner ist nicht Teil dieses Vertrags.

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

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:

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:

Beispiele:

nucli --tenant mandant-a diagnose
nucli --tenant mandant-a diagnose --json
nucli diagnose --all-tenants
nucli --tenant system readiness summary
nucli --tenant system system init status --json
nucli --tenant system system init plan --artifact workflow_library --json
nucli --tenant system --tenant-id 11111111-1111-1111-1111-111111111111 system diagnostics domain-access --domain workspace.example.com --json

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

system diagnostics domain-access erwartet eine System-Mandanten-Session mit system_diagnostics:read. --tenant-id bezeichnet bei diesem Befehl den Zielmandanten der Domain. nucli führt keine lokale DNS-, TLS-, Docker-, Reverse-Proxy- oder Ingress-Prüfung aus; der Server prüft nur Domains, die im Produkt für den Zielmandanten bekannt sind.

Weitere Diagnoseabläufe finden Sie unter Diagnose und Readiness.

Telemetrie-Fehler archivieren

Nutzen Sie telemetry snapshot, wenn Sie aktuelle Telemetrie-Fehler für den aktiven Mandanten archivieren und danach ohne historische Fehlerzeilen in die nächste Version starten möchten:

nucli --tenant mandant-a telemetry snapshot \
  --output telemetry-snapshot-2026-07-09.zip \
  --truncate \
  --reason "Release 2026.07 Baseline"

Der Server erzeugt das ZIP, löscht die erfassten Telemetrie-Gruppen und -Instanzen und schreibt den AuditLog-Eintrag. nucli sendet nur den Auftrag und speichert die Serverantwort. Der Befehl benötigt telemetry_errors:list, telemetry_errors:read und telemetry_errors:delete.

Mandantenkontext

Viele Befehle brauchen einen Mandantenkontext:

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

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

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.

Fachliche Ressourcen prüfen

Nutzen Sie nucli resources, wenn Sie tenantgebundene Admin-Ressourcen discovery-first prüfen möchten. Das CLI liest zuerst die veröffentlichten Ressourcen-Einstiege und danach die jeweilige Meta-Fläche.

Beispiel für Staff Teams:

nucli --tenant <tenant> resources list
nucli --tenant <tenant> resources meta staff.teams
nucli --tenant <tenant> resources get staff.teams --all --max-pages 5 --summary

staff.teams entspricht der Teamliste unter Personal > Teams. Die Ressource erscheint nur, wenn die aktuelle Session die passenden Staff-Team-Scopes hat. Teammitglieder oder andere Kindlisten können als eigene Nested-Ressource erscheinen, wenn der Server dafür einen CRUD-Metavertrag veröffentlicht. Setzen Sie dann die im Entrypoint sichtbaren Pfadparameter mit --param:

nucli --tenant <tenant> resources meta staff.teams.members --param teamId=<team-id>
nucli --tenant <tenant> resources create companies.employments --param companyId=<company-id> --input employment.json --summary

Fehlt ein erwarteter Nested-Entrypoint in resources list, fehlen der Session entweder passende Scopes oder der Server veröffentlicht für diese Kindliste keinen CRUD-Metavertrag.

Die fachliche Abgrenzung der Teamliste steht in Teams im Personalbereich.

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.

nucli --tenant <tenant> sites list --json
nucli --tenant <tenant> sites inspect <site-id>
nucli --tenant <tenant> sites kits list <site-id>
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.

sites inspect bündelt Workspace, Developer-Readiness, Operations-Readiness, Build-Status und Maintenance-State. Nutzen Sie --strict in Skripten, wenn der Befehl bei Blockern, fehlender Operations-Readiness oder fehlgeschlagenem Build abbrechen soll. sites kits list zeigt verfügbare Server-Kits, bevor Sie sites init --kit <name> ausführen.

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:

nucli --tenant <tenant> sites dev start <site-id> --review-window 7d
nucli --tenant <tenant> sites preview targets <site-id>
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 --json

Nutzen Sie --consumer anonymous für Reviewer ohne Login und nur für öffentliche Pfade aus sites preview targets beziehungsweise 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:

nucli --tenant <tenant> sites dev mount <site-id> --dry-run --json
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. Ergänzen Sie --json, wenn ein Skript den Mount-Plan maschinenlesbar auswerten soll; dafür müssen Sie die Site-ID explizit angeben.

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

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 create <site-id> pages/neue-seite.yaml --input neue-seite.json --json
nucli --tenant <tenant> sites files put <site-id> pages/index.de.yaml --input index.de.yaml --if-match <etag>
nucli --tenant <tenant> sites files delete <site-id> pages/alte-seite.yaml --if-match <etag>
nucli --tenant <tenant> sites files apply <site-id> --input patchset.json
nucli --tenant <tenant> sites files diff <site-id> --release <release-id>

files create erstellt eine neue Textdatei und schlägt fehl, wenn sie bereits existiert. Übergeben Sie als Input denselben JSON-Body wie bei files put, zum Beispiel {"content":"..."}. Für bestehende Dateien nutzen Sie weiter files get und den zurückgegebenen ETag mit files put oder files apply. files delete entfernt eine Quell-Datei im Dev-Workspace und verlangt den zuletzt gelesenen ETag. Löschen bereinigt den Quellstand, veröffentlicht aber nichts automatisch. Der Befehl darf keine Release-, Freeze- oder Live-Artefakte verändern und kann bei Fallback-Sites eine niedrigere Quellschicht wieder sichtbar machen. files diff vergleicht erlaubte Projektdateien nach Server-Dateipolicy gegen ein angegebenes Release.

Prüfen Sie Redirects und Routen vor einem Launch über Server-Diagnosen:

nucli --tenant <tenant> sites redirects list <site-id>
nucli --tenant <tenant> sites redirects test <site-id> --host www.example.com --input urls.txt
nucli --tenant <tenant> sites routes list <site-id>
nucli --tenant <tenant> sites routes list <site-id> --release live
nucli --tenant <tenant> sites route inspect <site-id> /pfad --host www.example.com
nucli --tenant <tenant> sites route inspect <site-id> /produkt/pfad --release live

redirects test simuliert Redirect-Ketten deterministisch gegen Redirect- und Routenzustand. Der Server führt keine freien HTTP-Aufrufe gegen --host aus. Ohne --release prüfen sites routes list und sites route inspect den Authoring-Zustand. Mit --release live oder --release <version> liest der Server veröffentlichte Artefakte wie redirects.yaml, routing.json und dynamic-routes.json und klassifiziert den Pfad aus Live-Sicht.

Für Produktdetail-Migrationen und Shop-Prüfungen liefert nucli PIM- und Commerce-Diagnosen als dünner Client auf Server-APIs:

nucli --tenant <tenant> pim attributes matrix --attribute-set <key>
nucli --tenant <tenant> pim variants inspect <variant-id-oder-sku> --sales-channel-id <channel-id> --locale de-DE --snippets product-detail-hero,product-detail-content
nucli --tenant <tenant> pim variants public-readiness <variant-id-oder-sku> --site <site-id> --snippets product-detail-hero,product-detail-content
nucli --tenant <tenant> pim publication diagnose <variant-id-oder-sku> --sales-channel-id <channel-id>
nucli --tenant <tenant> pim snippets status <variant-id-oder-sku> --sales-channel-id <channel-id> --locale de-DE --snippets product-detail-hero,product-detail-content
nucli --tenant <tenant> pim routes test --site <site-id> --input paths.txt
nucli --tenant <tenant> shop catalog search --site <site-id> --query "suchtext" --locale de-DE
nucli --tenant <tenant> shop category inspect --site <site-id> --path /kategorie --release live
nucli --tenant <tenant> commerce checkout smoke --site <site-id> --sku <sku> --quantity 1 --dry-run

Diese Befehle berechnen keine PIM-, Shop-, Preis-, Snippet- oder Checkout-Regeln im CLI. Der Server löst Site, Sales Channel, Locale, ProductRoute, Publication, Public Catalog, Snippet-Artefakte und Readiness auf und gibt stabile Status- und Reason-Keys zurück. checkout smoke verlangt immer --dry-run; der Server erstellt dabei keine Bestellung, keine Zahlung und keine Checkout-Nachrichten.

Verwenden Sie für --snippets die exakten, groß-/kleinschreibungssensitiven Namen aus sites route inspect --release <release> oder aus der productSnippet-Komponente der Site. pim variants inspect, pim variants public-readiness und pim snippets status normalisieren diese Namen nicht.

Variantenmatrix prüfen

pim variants inspect zeigt zusätzlich, ob der Server für die gewählte Produktvariante eine öffentliche Variantenmatrix bilden kann:

variants: available=true combinations=3 routed=2 routeLess=1

combinations zählt vollständige public-safe Kombinationen. routed zählt Kombinationen mit ProductRoute, routeLess Kombinationen ohne eigene Browser-URL. Ein Wert größer null bei routeLess ist kein Publication-Fehler. Mit --json erhalten Sie dieselben Werte unter variants und zusätzlich axisKeys.

Wenn available=false erscheint, nennt die Ausgabe nach dem Trennzeichen den Grund, zum Beispiel:

variants: available=false combinations=0 routed=0 routeLess=0 | variant_axis_not_available

Eine nicht verfügbare Variantenmatrix betrifft die Variantenauswahl. Sie bedeutet nicht automatisch, dass die aktuell geprüfte Produktvariante unveröffentlicht ist. Der Shop rendert diese Variante dann ohne Variantenauswahl.

Geben Sie bei Produkt-, Routen-, Pricing- und Snippet-Prüfungen immer den konkreten Storefront-Scope an. --sales-channel-id beschreibt den Markt mit Währung, Preisliste, Steuer- und Checkout-Regeln. --locale beschreibt Sprache und regionale Schreibweise. Raten Sie weder Währung noch Land aus der Sprache, besonders wenn dieselbe Sprache in mehreren Ländern oder mehrere Sprachen im selben Land genutzt werden.

Nutzen Sie für Automatisierung immer --json. Die JSON-Ausgabe enthält das serverseitige Ergebnis mit status, reasonKey, Detailbefunden und dem zuständigen Bereich. Ein erfolgreicher Check meldet ready oder reachable. Ein blockierter Check nennt die Ursache maschinenlesbar, zum Beispiel fehlende Publication, fehlende Route, fehlenden Preis, fehlende Pflicht-Snippets oder fehlende Checkout-Voraussetzungen.

Die wichtigsten Diagnosebefehle:

pim snippets status meldet den Artefakt-Dateistatus als present, missing, metadata_missing, metadata_invalid oder unknown. unknown bedeutet, dass der Server keinen belastbaren lokalen Public-Asset-Storage für diese Diagnose nutzen kann. Das ist Absicht: Der Server rät keine Dateipfade. shop catalog search ist eine Admin-Diagnose und schreibt keine öffentliche Suchanalyse oder Rate-Limit-Zähler.

Regelmäßige End-to-End-Prüfungen gegen den Live-Shop brauchen zusätzlich einen vertrauenswürdigen synthetischen Ausführungskontext. commerce checkout smoke ist dafür kein Ersatz, weil der Befehl absichtlich keine Bestellung und keine Zahlung erzeugt. Den Ablauf für produktionsnahe Browserprüfungen beschreibt Synthetische Shop-Prüfungen.

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

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

Nach der Initialisierung bleiben Build und Veröffentlichung getrennt:

nucli --tenant <tenant> sites build <site-id> --wait --json
nucli --tenant <tenant> sites build-status <site-id>
nucli --tenant <tenant> sites releases list <site-id>
nucli --tenant <tenant> sites publish plan <site-id> --release <release-id>
nucli --tenant <tenant> sites publish <site-id> --release <release-id> --json

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. build-status zeigt den aktuellen oder letzten Build-Status; releases list zeigt die exakten Release-Versionen, die Sie an publish übergeben können. publish plan prüft read-only Release, Operations-Readiness und Diff-Zusammenfassung; der Befehl baut und veröffentlicht nicht. Git-Deploy folgt demselben Vertrag: Der Vorgang erzeugt einen Release-Stand, schaltet ihn aber nicht live.

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

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:

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:

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.

Tenant-Featureflags werden ebenfalls über unterstützte System-Admin-Endpunkte geschrieben. Verwenden Sie dafür keinen direkten Datenbankzugriff:

nucli --tenant system api GET /api/v1/system/features/catalog --summary
nucli --tenant system api GET '/api/v1/system/tenants/<tenant-id>/features/assignments?entityType=ai' --summary
printf '{"isEnabled":true,"isRequired":false}' \
  | nucli --tenant system api PUT /api/v1/system/tenants/<tenant-id>/features/assignments/ai/inbox.triage --input - --summary

Der Server akzeptiert diese Schreibzugriffe nur aus dem System-Tenant, validiert den Zielmandanten und den Feature-Key gegen den Katalog und aktualisiert den Laufzeit-Cache für Feature-Gates.

Provider-Verbindungen wie Google Merchant Center oder Google Search Console richten Sie im OAuth-Wizard unter System > Integrationen > Provider-Verbindungen ein. nucli hat keinen eigenen OAuth-Onboarding- Befehl, weil OAuth-Start, Zustimmung und Callback eine Browser-Session mit Origin-Prüfung verwenden. Nutzen Sie nucli api hier nur für Prüfung und Dokumentation:

nucli --tenant <tenant> api GET /api/v1/provider-connections --redact --save provider-connections.json
nucli --tenant <tenant> api POST /api/v1/provider-connections/<credentialId>/test --summary
nucli --tenant <tenant> api POST /api/v1/commerce/config/product-channel-bindings --input product-channel-binding-google-merchant.json --summary
nucli --tenant <tenant> api GET /api/v1/commerce/config/product-channel-bindings/<bindingId>/readiness --summary
nucli --tenant <tenant> api GET /api/v1/commerce/config/product-channel-bindings/<bindingId>/sync-runs --summary
nucli --tenant <tenant> api GET /api/v1/commerce/config/product-channel-bindings/<bindingId>/item-states --summary

Für Google Merchant Center ist Product Channel Sync der fachliche Ablauf. Wenn Sie einen Sync über nucli api starten, senden Sie einen expliziten JSON-Body:

printf '{}' | nucli --tenant <tenant> api POST /api/v1/commerce/config/product-channel-bindings/<bindingId>/sync --input - --summary

Die vollständige Merchant-Schrittfolge steht in Product Channel Sync für Google Merchant Center einrichten. Die allgemeine OAuth-Vorbereitung steht in Provider-Verbindungen einrichten.