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.

Eine eng begrenzte Ausnahme gilt für Workspace Sites: Externe Entwickler können Site Packages mit nucli sites package lokal prüfen und bauen und sie mit nucli sites store an den getrennten Sites-Dienst übertragen. Diese Befehle verwalten keinen Workspace und gewähren keinen Tenant-Zugriff. Der vollständige Ablauf steht unter Sites entwickeln und bereitstellen.

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/.

Auf Linux, macOS und den unterstützten BSD-Systemen können Sie stattdessen NUCLI_STORE_KEY_FILE auf eine private Schlüsseldatei setzen. Sie muss Ihnen gehören, regulär sein und den Modus 0600 besitzen. NuCLI liest höchstens 4096 Bytes, lehnt Symlinks und leere Dateien ab und verwendet den unveränderten Inhalt als Schlüssel. Setzen Sie NUCLI_STORE_KEY und NUCLI_STORE_KEY_FILE nicht gleichzeitig.

Mit einer ausdrücklich ausgewählten Schlüsseldatei nutzt NuCLI ausschließlich den verschlüsselten Dateistore. Ist die Datei ungültig oder nicht lesbar, endet der Zugriff mit einem Fehler; NuCLI verwendet dann weder den Secret Service noch ein Environment-Token. Auf anderen Plattformen ist dieser Dateivertrag nicht verfügbar.

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.

Browseranmeldung und lokaler Zugang

Mit --browser übergeben Sie die Anmeldung an den Browser. Der Server muss diesen Anmeldeweg anbieten:

nucli --host <workspace-url> login --browser

Der Browser zeigt die für den Mandanten verfügbaren Anmeldewege. Eine zentrale Anmeldung über OpenID Connect (OIDC) setzt zusätzlich eine freigeschaltete und eingerichtete Verbindung voraus. Die Browseranmeldung allein bestätigt das nicht. Rollen, Rechte und Mitgliedschaften bleiben beim jeweiligen Workspace.

Ohne Zusatzoption wählt login den Browser erst, wenn der Server die OIDC-Login-Unterstützung ausdrücklich bekannt gibt. Bei älteren Servern bleibt die lokale Anmeldung erhalten. --email, --password-stdin und --otp wählen weiterhin den lokalen Weg. Mit --local können Sie ihn ausdrücklich wählen:

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

Nutzen Sie diesen Weg für den System-Mandanten und bei einem Ausfall des zentralen Anbieters. Sie benötigen dafür bereits vorhandene lokale Zugangsdaten und gegebenenfalls den vorgeschriebenen zweiten Faktor. --local ersetzt keine Berechtigung und erzeugt kein neues Benutzerkonto. Kombinieren Sie --browser nicht mit lokalen Anmeldeoptionen.

Die mandantenweise Capability-Freischaltung nutzt den vorhandenen System-Admin-Vertrag. Prüfen Sie zuerst den System-Mandanten und den Scope feature_flags:update, und senden Sie dann die ausdrückliche Zuweisung für den Zielmandanten:

nucli --tenant system whoami --scopes
printf '{"isEnabled":true,"isRequired":false}' \
  | nucli --tenant system api PUT \
      /api/v1/system/tenants/<tenant-id>/features/assignments/auth/auth.upstream_oidc_login \
      --input - --summary

Der System-Mandant kann denselben Vertrag mit isEnabled:false zum Deaktivieren verwenden. Für OIDC-Verbindungen und Zulassungsregeln gibt es keinen eigenen nucli- oder mutierenden MCP-Befehl; verwalten Sie diese im Zielmandanten über Anmeldung > OIDC-Verbindungen und Anmeldung > Zulassungsregeln.

Ohne interaktives Terminal öffnet nucli keinen Browser. Es zeigt eine kurzlebige Bestätigungsadresse und einen Vergleichscode an und wartet auf die Freigabe. Behandeln Sie die Adresse vertraulich und übernehmen Sie sie nicht in Protokolle. Prüfen Sie nach erfolgreicher Freigabe mit nucli whoami --json die gespeicherte Sitzung und den aktiven Mandanten. --tenant-id schützt dabei gegen einen unerwarteten Zielmandanten; die Option gewährt keine Mitgliedschaft.

Tenant-ID finden

Die mandantenweise Freischaltung, Organisationsregeln und lokale Notfallzugänge beschreibt Anmeldung über einen zentralen Identity Provider. Eine zentrale Anmeldung gibt nucli keine zusätzlichen Mitgliedschaften oder Rollen.

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

Für Browseranmeldung, lokalen Zugang und die Prüfung der serverseitigen Login-Fähigkeiten verwenden Sie nucli skills show oidc-login-federation. Der Skill enthält keine Befehle zur Einrichtung eines zentralen Anbieters.

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 deployment, wenn ein Agent bei Erstinstallation, Update, Product-Release-Maintenance oder Recovery unterstützt. Der Skill wählt den passenden Docker-, Paket-, Standalone- oder Kubernetes-Pfad, trennt Pre-Login-Diagnose von authentisierter Serverdiagnose und verhindert einen Binary-Rollback nach dem Schema-Point-of-No-Return. Er nennt außerdem für jeden Installationskanal die geschützte Bootstrap-Credential-Datei, verbietet Agenten das Auslesen ihrer Secrets und führt bis zum geprüften Erstlogin und der anschließenden Entfernung des Bootstrap-Artefakts. Für Mandanten im System-Mandanten ist nucli skills show tenant-administration vorgesehen. Der Skill deckt Auflistung, Planung, idempotente Anlage und Provisionierungsstatus ab. Er verlangt Discovery, passenden Systemkontext, effektive Scopes und die ausdrückliche Freigabe des unveränderten MCP-Plans. Der gleichlautende MCP-Einstieg heißt nucleus_tenant_administration_skill. Site-Dateien, Tenant Domains, Preview, Build, Publish-Plan und bewusste Veröffentlichung begleitet nucli skills show sites. Der Skill trennt Developer- von Operations-Readiness und behandelt Preview-Handoffs als kurzlebige Einmal-Tokens. Er beschreibt außerdem den sitegebundenen, nur lesenden Zugriff auf Site Insight mit nucli sites insight. Der MCP-Einstieg heißt nucleus_sites_skill; den Bericht liest nucleus_site_insight. Einbau, Messumfang und Datenschutzgrenzen erklärt Site Insight einbauen. Den zusammenhängenden Weg von Installation und Systemzugang über den Fachmandanten bis zur veröffentlichten Site zeigt Von der Docker-Demo zur ersten Live-Site. Nutzen Sie nucli skills show emergency-release, wenn ein Agent einen signierten runtime_only-OCI-Hotfix begleitet. Der Skill trennt externes Signatur-Gate, read-only DeploymentPlan, Canary, ausdrückliche Infrastrukturfreigabe, Primär-Readback und den nur bei erneut bestätigter Kompatibilität erlaubten Rückweg. Der gleichlautende MCP-Einstieg heißt nucleus_emergency_release_skill; die strukturierte Einordnung vorhandener Gate-Ergebnisse übernimmt nucleus_emergency_release_assess. 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. nucli skills show manufacturing-refurbishment begleitet die Aufbereitung oder technische Umrüstung genau eines serialisierten Geräts. Der Skill liest zuerst Berechtigungen, Plan, Bestand und zulässige Workflow-Übergänge. Vor jeder Änderung verlangt er eine ausdrückliche Freigabe; die Buchung bestätigt er nur mit dem frischen Token aus der unmittelbar vorausgegangenen Vorschau. Bei einer mehrdeutigen Seriennummernzuordnung oder fehlender Workflow-Konfiguration bricht er ab. Direkte Datenbankzugriffe sind kein Ersatz. Der Skill trennt außerdem technische Varianten von Zustand, Foto und dem Angebot für das konkrete Einzelstück. Den fachlichen Ablauf erklärt Fertigung und Auftragsfertigung.

nucli skills show individual-unit-offers übernimmt den anschließenden Admin-Ablauf für genau dieses Stück. Er beginnt auf Wunsch bereits beim internen Ankauf: Entwurf und Positionen erfassen, einen privaten geprüften Beleg binden und den Erwerb über die eigene acquire-Aktion buchen. Dabei verwendet Workspace den vorhandenen Wareneingangs-, Bestands-, Kosten- und Buchhaltungsprozess. Ein Entwurf lässt sich über die eigene cancel-Aktion beenden; nach dem Erwerb ist das nicht mehr möglich.

Global lassen sich Aktivierung und Modus vorgeben und pro Mandant überschreiben. Die Werte storage.scan.clamav_address und storage.scan.timeout_ms verwaltet der Betreiber dagegen ausschließlich systemweit. Prüfen Sie die für den Mandanten wirksamen Werte vor dem Upload:

nucli --tenant <tenant> api GET /api/v1/config-values/definitions/values \
  --save individual-unit-storage-scan-config.json

Für den Aufruf benötigen Sie configvalues:read. Suchen Sie in der Antwort nach den beiden Schlüsseln und prüfen Sie jeweils value und source. Setzen Sie den Ablauf erst fort, wenn storage.scan.enabled wirksam true und storage.scan.mode wirksam clamav meldet. Ohne Leseberechtigung oder einen betriebsbereiten ClamAV-Dienst muss der zuständige Betreiber die Voraussetzung prüfen und herstellen. Der Einzelstückablauf ändert diese Konfiguration nicht selbst.

Soll ein bereits erworbenes Stück an den Verkäufer zurückgehen, verwendet der Skill stattdessen die eigene reverse-Aktion mit einem Pflichtgrund. Die Rückabwicklung bleibt als eigener Verlauf erhalten; der Ankauf selbst behält den Status acquired. In einer gemeinsamen Transaktion bucht Workspace den Bestandszugang und den Ankauf gegen, setzt das serienverfolgte Stück auf returned_to_seller, verbraucht seine unberührte Kostenlage und storniert den vollständig offenen Kreditorenposten. Reservierte, angebotene oder bereits verbrauchte Stücke sowie ganz oder teilweise bezahlte Posten werden abgewiesen. Das gilt auch für Barankäufe: Sie benötigen einen getrennten Erstattungs- und Zahlungsabgleich, den dieser Ablauf nicht ersetzt. Nach einer erfolgreichen Rückabwicklung kann dieselbe Serienidentität in einem neuen Ankauf wiederverwendet werden; die frühere Historie bleibt unverändert.

Die Zahlungsart wird ausdrücklich als settlementMode erfasst. payable benötigt Fälligkeit und Zahlungsbedingung und erzeugt einen offenen Posten. cash steht für eine sofortige Zahlung. Sie lässt diese beiden Felder leer, verlangt aber mit settlementAccountId das konkrete aktive Kassen- oder Bankkonto. Dieses Konto wird direkt als Gegenkonto gebucht; ein offener Posten entsteht nicht. Fehlende Zahlungsbedingungen werden nicht als Barzahlung ausgelegt. Als steuerliche Verkäuferkategorie sind nur Privatankäufe ohne Umsatzsteuerausweis und Unternehmensankäufe ohne abzugsfähige Vorsteuer zulässig. Ein steuerpflichtiger Unternehmensankauf benötigt einen eigenen Steuerprofilvertrag und wird bis dahin abgewiesen.

Für den Verkauf prüft der Skill Zustandsstand, privates Verkaufsfoto, Tracking und serverseitige Readiness, bevor er eine Aktivierung des Angebots vorschlägt. Jede Mutation benötigt eine eigene ausdrückliche Freigabe und die aktuelle erwartete Revision. Soll eine aktive Revision ersetzt werden, bindet der Skill den Tausch zusätzlich an die zuvor gelesene aktive Revision. Beim Aktualisieren eines Entwurfs sendet er nur die neue Angebotsrevision; Angebot und Vertriebskanal bleiben serverseitig geschützt. Anschließend liest er den Listingeintrag erneut und prüft alle drei Bindungen.

Ein aktives Angebot wird erst durch einen veröffentlichten Listingeintrag im Public Storefront sichtbar. Kunden legen dessen öffentliche Kennung zusammen mit der erwarteten Angebotsrevision in den Standard-Warenkorb. Workspace hält dann genau dieses Stück mit Menge eins. B2C-Kunden und verifizierte B2B-Käufer können den normalen Checkout verwenden. Noch nicht verifizierte Unternehmen bleiben auf den Angebotsweg beschränkt; beim Erzeugen des Angebots wird der kurze Warenkorb-Hold freigegeben. Die spätere Bestellung muss dasselbe Stück erneut erwerben oder endet ohne Ersatzstück.

Ein Listingeintrag wird über die tenantgebundene publish-Aktion von draft nach published überführt. Der Skill liest Angebot und Listing unmittelbar zuvor neu und sendet die erwartete aktive Angebotsrevision mit. Der Server prüft Verkaufskanal, gültigen Kanalpreis und konkurrierende Reservierungen. Die getrennte withdraw-Aktion zieht einen veröffentlichten Eintrag zurück; allgemeines CRUD darf den Lifecycle-Status nicht setzen.

Beim Platzieren der Bestellung wechselt das Angebot zu committed. Die maßgebliche Versand- oder Übergabebuchung setzt es auf sold; eine endgültige Auftragsstornierung setzt es auf withdrawn. Ein automatisches Relisting gibt es nicht. Für ein Wiederangebot liest der Skill das jüngste terminale Angebot erneut und nutzt mit der Berechtigung individual_unit_offers:relist dessen eigene relist-Aktion. Der Server verlangt, dass genau ein serienverfolgtes Stück mit Menge eins wieder frei im Bestand verfügbar ist. Er legt einen neuen Entwurf an und lässt den bisherigen Verlauf unverändert. Vor der Aktivierung müssen Sie einen neuen Zustandsstand abschließen; ein bereits in einem anderen Angebot verwendeter Zustandsstand blockiert die Readiness. Der allgemeine Create-Endpunkt bleibt für das erste Angebot einer Serienidentität reserviert.

Die Mengeneinheit muss im Mandanten vorhanden und als Stückeinheit (dimension=count) geführt sein; Readiness und Aktivierung prüfen das erneut. Preise müssen positiv und ohne Rundung als numeric(19,4) darstellbar sein, also höchstens 15 Vorkommastellen und vier wirksame Nachkommastellen besitzen.

Die Differenzbesteuerung bleibt gesperrt. Die 27 inventarisierten EU-Länderprofile stehen derzeit ausnahmslos auf PENDING und dürfen nicht aktiviert werden. Workspace fällt weder auf Standardbesteuerung noch auf Steuersatz null, Steuerfreiheit oder einen Rabatt zurück. Für Fotos eines Einzelstücks reichen allgemeine Storage-Rechte oder eine Objektfreigabe allein nicht aus. Der Agent benötigt zusätzlich die zur Aktion passende Fachberechtigung für Einzelstückfotos. Das gilt für Upload, Liste und Lesen ebenso wie für Änderung und Löschung. Änderungen an den Metadaten verlangen Lese- und Änderungsberechtigung, weil die Antwort das aktualisierte Objekt enthält. Fehlt eine erforderliche Fachberechtigung, bricht der Ablauf vor der Änderung ab. Nutzen Sie nucli skills show mail, wenn ein Agent persönliche oder gemeinsame Postfächer, Verteiler, Mail-Arbeitszustände oder Zustellstatus prüft. Der Skill beginnt mit lesenden Prüfungen, nutzt ausschließlich tenantgebundene Mail-APIs und verlangt vor Administration, Versand oder Änderungen am Arbeitszustand eine ausdrückliche Freigabe. Gateway- und DNS-Änderungen bleiben außerhalb dieses Ablaufs. Für die erste produktive Postmark-Inbetriebnahme führt er zusätzlich durch die begleitete Pilotabnahme. Er prüft den Workspace- DNS-Nachweis, die providerseitige Erreichbarkeit der Webhooks, die aktive Transportrevision und genau einen freigegebenen Testversand bis zum Delivery-Callback. Benötigte Antwortfelder bleiben in einem geschützten temporären Verzeichnis; Zugangsdaten, Aktivierungstoken und Nachrichteninhalte werden weder in Befehlsargumente noch in Abnahmeprotokolle übernommen. Die Einrichtung ist unter Mail und Benachrichtigungen beschrieben. Die Bereitstellung eines eigenen Gateways erklärt Mail mit einem SMTP-Gateway bereitstellen. 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. Nutzen Sie nucli skills show root-key-rotation, wenn ein Agent zwischen Legacy-Bundle-Migration, Routine, Emergency und Abbruch unterscheiden soll. Der Skill erklärt die verpflichtenden Gates, greift aber nie auf lokale Key-Dateien, Konfiguration, Datenbank oder Storage zu. Den Ablauf für Administratoren erklärt Root-Key sicher rotieren.

nucli skills list
nucli skills show deployment
nucli skills show tenant-administration
nucli skills show sites
nucli skills show emergency-release
nucli skills show operations
nucli skills show commerce-shipping
nucli skills show pim-product-maintenance
nucli skills show manufacturing-refurbishment
nucli skills show individual-unit-offers
nucli skills show mail
nucli skills show system-artifacts
nucli skills show root-key-rotation

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 Site- und Domain-Aufgaben verlangen genau diese 13 mutierenden Tools den erforderlichen JSON-Boolean approved: true:

• nucleus_site_files_apply
• nucleus_site_backup_save
• nucleus_site_restore_apply
• nucleus_site_dev_start
• nucleus_site_preview_link_request
• nucleus_site_dependencies_add
• nucleus_site_dependencies_sync
• nucleus_site_build
• nucleus_site_publish
• nucleus_tenant_domain_create
• nucleus_tenant_domain_start_verification
• nucleus_tenant_domain_verify_dns
• nucleus_site_domain_bind

Fehlt approved, ist der Wert false, null oder kein Boolean, stoppt nucli den Aufruf vor Datei-, Secret-, Netzwerk- und Serverzugriff. Das Feld bleibt im lokalen MCP-Adapter und wird nicht an Workspace gesendet. Es ersetzt weder Anmeldung, Berechtigungen, Tenantbindung, Idempotenz, Fachvalidierung noch serverseitiges Audit. Die Freigabe gilt ausschließlich für den übrigen Payload desselben Tool-Aufrufs. Read-only-Tools sowie nucleus_site_validate und nucleus_site_restore_preview bleiben unverändert.

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 read-only MCP-Einstieg nucleus_deployment_skill gibt denselben Installations- und Updatevertrag wie nucli skills show deployment aus. nucleus_deployment_assess ordnet normalisierte Installations- und Updatebeobachtungen ein. Diese vier Skill- und Assessment-Tools arbeiten lokal ohne HTTP-Aufruf. Sie benötigen deshalb weder Login noch funktionierende Readiness und eignen sich gerade für den fail-closed Startzustand.

Installation oder Update strukturiert einordnen

nucleus_deployment_assess benötigt immer:

Optional ergänzen Sie releaseStatus, den stabilen errorCode, loginHttpStatus, tlsValidationFailed, transitionClass und pointOfNoReturnReached. Verwenden Sie für live nicht das Feld eines alten Maintenance-Payloads. Ermitteln Sie Liveness und Readiness separat.

Beispiel für einen lebenden Server im kontrollierten Retry:

{
  "operation": "first_install",
  "live": true,
  "ready": false,
  "releaseStatus": "retry_wait",
  "errorCode": "product_release_component_failed",
  "transitionClass": "unknown",
  "pointOfNoReturnReached": false
}

Das Ergebnis enthält unter anderem:

{
  "contractVersion": "nucleus-deployment-assessment/v1",
  "classification": "release_retry_wait",
  "readyForLogin": false,
  "versionAction": "keep_current",
  "recoveryMode": "wait_and_diagnose_same_release"
}

Die Klassifikation beantwortet damit ausdrücklich die Versionsfrage: Bei retry_wait bleibt die aktuelle Zielversion ausgewählt. Ein HTTP 401 vor Readiness führt zu pre_ready_authentication_required; der Agent soll dann nicht das Benutzerpasswort erraten, sondern den Administrator den geschützten Bootstrap-System-API-Key über --token-stdin verwenden lassen. Bei einem erreichten forward_only-Point-of-No-Return liefert das Assessment forward_recovery_required und verbietet die alte Binary.

Das Tool liefert außerdem konkrete nextSteps, stopConditions und die Felder, die ohne Secrets in ein Support-Ticket dürfen. Es liest weder Logs noch Credential-Dateien. Übergeben Sie keine Passwörter, Tokens, Cookies, Runtime-Keys, privaten TLS-Schlüssel, verschlüsselte Konfiguration oder Backup-Inhalte.

Emergency-Release-Gates strukturiert einordnen

nucleus_emergency_release_assess erwartet phase sowie die separat ermittelten booleschen Ergebnisse für exakte Digests, Signatur, Attestation, runtime_only, Live-DeploymentPlan, Canary, externe Freigabe, Primär-Readback, Zustandsänderung und weiterhin erlaubten Rückweg. Ein boolescher Wert dokumentiert nur eine vorhandene Prüfung; das Tool führt die Prüfung nicht selbst aus.

Das Tool arbeitet strikt in Gate-Reihenfolge. Es stoppt beispielsweise mit immutable_identity_required, supply_chain_verification_required, normal_update_required, live_plan_required, canary_required oder awaiting_external_approval. Nur external_activation_handoff_ready bezeichnet eine vollständige Übergabe an die Infrastruktur. Selbst dann ändert das Tool keinen Pin. Im Rückweg meldet nur binary_switch_eligible einen möglichen exakten Quellimage-Swap; bei Zustandsänderung folgt forward_recovery_or_restore.

Den vollständigen Vertrag und die Herkunft jedes Eingabefelds erklärt Agentenunterstützung ohne automatische Freigabe.

Für Root-Key-Rotation liefert nucleus_root_key_rotation_skill ausschließlich die sichere Entscheidungs- und Prüfanleitung. Das Tool nimmt keine Key-Werte oder lokalen Dateipfade entgegen und führt keine Rotation aus.

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.

SMTP-Passwort für mehrere Mandanten rotieren

Nutzen Sie nucli credentials smtp rotate, wenn mehrere ausdrücklich benannte Mandanten dasselbe neue SMTP-Passwort erhalten sollen. Der Befehl arbeitet jeden Mandanten mit seinem eigenen lokalen Profil, seiner eigenen persistenten Session und seiner aktiven Tenant-ID ab. Er benötigt je Profil mailConfig:read, mailConfig:update und mailConfig:test-connection.

Prüfen Sie zuerst die Profile und ermitteln Sie die jeweilige MailConfig-ID:

nucli profiles
nucli --tenant mandant-a whoami --json
nucli --tenant mandant-a resources get mail-configs --all
nucli --tenant mandant-b whoami --json
nucli --tenant mandant-b resources get mail-configs --all

Jedes Zielprofil braucht eine zuvor mit nucli login gespeicherte Session. Ein einzelnes NUCLI_TOKEN ersetzt diese profilgebundenen Sessions für die Mehrmandantenrotation nicht.

Halten Sie das bisherige Provider-Passwort aktiv. Lesen Sie das neue Passwort verdeckt ein und übergeben Sie es ausschließlich über Standard Input:

IFS= read -r -s -p 'Neues SMTP-Passwort: ' SMTP_ROTATION_PASSWORD
printf '\n'
printf '%s\n' "$SMTP_ROTATION_PASSWORD" |
  nucli credentials smtp rotate \
    --target mandant-a=11111111-1111-4111-8111-111111111111 \
    --target mandant-b=22222222-2222-4222-8222-222222222222 \
    --password-stdin
unset SMTP_ROTATION_PASSWORD

Schreiben Sie das Passwort nicht in Argumente, Eingabedateien oder Shell-Historien. Für eine maschinenlesbare Ergebnisausgabe ohne Passwortwerte ergänzen Sie --json.

Vor der Passworteingabe prüft nucli alle Profile, persistenten Sessions, aktiven Tenant-IDs, serverdeklarierten Aktionen, Berechtigungen und MailConfig-IDs. Schlägt dieser vollständige Preflight fehl, liest der Befehl kein Passwort und ändert keinen Mandanten. Danach aktualisiert er jedes Ziel tenantweise und testet die gespeicherte Verbindung mit dem neuen Passwort.

Ein Fehler bei einem Ziel stoppt die übrigen vorab geprüften Ziele nicht. Der Befehl endet dann mit einem Exit-Code ungleich null und meldet pro Alias nur Status und stabilen Fehlercode. Lassen Sie das bisherige Provider-Passwort in diesem Fall aktiv, beheben Sie den gemeldeten Fehler und wiederholen Sie den gesamten Befehl mit demselben neuen Passwort. Der Ablauf führt keinen tenantübergreifenden Rollback aus.

Eine tatsächliche Passwortänderung setzt die Bestätigung der MailConfig zurück. Senden Sie nach erfolgreicher Rotation pro Mandant eine Test-Mail und bestätigen Sie deren Eingang im Mailserver-Assistenten. Widerrufen Sie das alte Provider-Passwort erst, wenn alle Verbindungstests erfolgreich waren. Die gespeicherten MailConfig-Änderungen benötigen keinen Serverneustart.

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.

Mitarbeiterzuordnungen eines Unternehmens prüfen

Eine Mitarbeiterzuordnung verbindet eine Person mit einem Unternehmen. Für den Detailaufruf brauchen Sie die Kennung dieser Zuordnung und die Kennung des Unternehmens. Die Personenkennung führt zum Personendatensatz und ist nicht die Kennung der Mitarbeiterzuordnung. Wählen Sie außerdem den Workspace, in dem das Unternehmen geführt wird.

Prüfen Sie zuerst Ihre Rechte und den veröffentlichten Ressourcenvertrag:

nucli --tenant <tenant> whoami --scopes
nucli --tenant <tenant> resources meta companies.employments --param companyId=<company-id>
nucli --tenant <tenant> resources get companies.employments --param companyId=<company-id> --all --max-pages 5 --redact --save company-employments.json
nucli --tenant <tenant> resources get companies.employments <employment-id> --param companyId=<company-id> --summary

Ersetzen Sie die Platzhalter durch den gewünschten Workspace, das Unternehmen und die Kennung einer Mitarbeiterzuordnung aus dessen Liste. Die Liste benötigt companies_employment:list, der Detailaufruf companies_employment:read. Werten Sie die gespeicherte Antwort lokal aus; geben Sie Namen und andere persönliche Felder nicht in Diagnoseberichten weiter. Bei einer überschrittenen Seitengrenze ist die Suche unvollständig.

Wenn der Server diesen Ressourceneinstieg nicht veröffentlicht, verwenden Sie denselben unternehmensgebundenen HTTP-Vertrag:

nucli --tenant <tenant> api GET '/api/v1/companies/<company-id>/employments?count=100' --redact --save company-employments.json
nucli --tenant <tenant> api GET '/api/v1/companies/<company-id>/employments/<employment-id>' --summary

Prüfen Sie bei der API-Liste die gemeldete Gesamtzahl und holen Sie weitere Seiten, falls die Antwort noch nicht alle Zuordnungen enthält. Ein einzelner Listenausschnitt belegt nicht, dass eine Zuordnung fehlt.

Der Detailpfad benötigt immer die Unternehmenskennung. Ein Aufruf ohne diese Kennung ist kein unterstützter Ersatz und kann „nicht gefunden“ zurückgeben, obwohl der korrekte unternehmensgebundene Aufruf funktioniert. Auch ein falsches Unternehmen oder ein anderer Workspace kann diese Meldung erklären. Prüfen Sie daher Kontext, Berechtigungen und die Zuordnungskennung, bevor Sie eine Löschung vermuten oder Daten neu anlegen. In der Oberfläche öffnen Sie Details erneut aus der Mitarbeiterliste des richtigen Unternehmens. Der Benutzerablauf steht in Kundendaten und Kontakte pflegen.

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 --locale de-DE --jurisdiction global
nucli --tenant <tenant> sites route inspect <site-id> /produkt/pfad --locale de-DE --jurisdiction de-b2c --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. Bei sites route inspect bestimmen --locale, --jurisdiction und optional --release den angefragten Scope. Der frühere Route-Parameter --host ist entfallen und wird bei nachgestellter Verwendung mit einem Migrationshinweis abgelehnt. Wenn Sie stattdessen den Workspace-Server wechseln müssen, setzen Sie den globalen Parameter vor den Befehl: nucli --host https://workspace.example.com --tenant <tenant> sites route inspect …. Die normale Ausgabe zeigt zuerst den Primärbefund und danach jede Warnung in einem eigenen Abschnitt; interne Artefaktpfade werden nicht ausgegeben. Mit --json erhalten Sie die Serverantwort unverändert. Die CLI berechnet weder Scope noch Routenpriorität und liest keine Site-Manifeste.

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 change-sku <varianten-id> --new-sku <neue-sku>
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 snippets rebuild --resource-type variant
nucli --tenant <tenant> pim snippets rebuild --resource-type catalog_product
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.

pim variants change-sku zeigt standardmäßig nur die serverseitige Vorschau. Sie nennt Workflow-Status, betroffene offene Angebotspositionen, erhaltene Referenzen und mögliche Blocker. Erst --apply führt die Korrektur aus:

nucli --tenant <tenant> pim variants change-sku <varianten-id> \
  --new-sku <neue-sku> \
  --apply \
  --reason "Korrektur eines Importfehlers" \
  --idempotency-key <stabiler-schlüssel>

Der Befehl liest vor --apply erneut die Vorschau und zeigt sie auf stderr an. Für neue Korrekturen muss diese Vorschau erfolgreich sein. Ohne --expected-current-sku übermittelt die CLI den dort gelesenen Istwert als Nebenläufigkeitsschutz. Mit dem Flag können Sie den ursprünglich gelesenen Wert ausdrücklich übergeben; Leerzeichen bleiben erhalten, auch ein explizit leerer Wert ist möglich.

Wiederholen Sie eine bereits abgeschlossene Korrektur mit demselben Schlüssel, Zielwert, ursprünglichen Istwert und derselben Begründung. Wenn die aktuelle Vorschau blockiert, liest der Befehl mit --expected-current-sku ausschließlich den gespeicherten Erfolg. Er legt dann keinen Auftrag an und ändert keine Daten. Fehlt ein passender abgeschlossener Auftrag, endet die Wiederholung als Konflikt. --json hält stdout frei von Vorschautext.

nucli --tenant <tenant> pim variants change-sku <varianten-id> \
  --new-sku <neue-sku> \
  --expected-current-sku "<ursprüngliche-sku>" \
  --apply --reason "Korrektur eines Importfehlers" \
  --idempotency-key <stabiler-schlüssel> --json

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.

pim snippets rebuild plant einen vollständigen Neuaufbau für den gewählten Ressourcentyp. Verwenden Sie variant für Varianten-Snippets und catalog_product für Katalogprodukt-Snippets. Mit --locale und --sales-channel-id lässt sich der Auftrag auf einen Scope begrenzen; --force legt auch bei einem bereits aktiven passenden Auftrag einen neuen Job an.

Der tenantweite Neuaufbau der Public-Catalog-Suchprojektion ist dagegen eine geschützte Systemoperation. Verwenden Sie dafür nicht den generischen API-Befehl, sondern den geführten Ablauf unter Public-Catalog-Suchprojektion kontrolliert neu aufbauen.

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.

Für Git-Deploy muss der Betreiber das HTTPS-Ziel installationsweit unter cms.git.egress.allowed_destinations freigeben. Der Standardwert [] sperrt alle Ziele. Ein Eintrag benennt einen exakten DNS-Host und die erlaubten Ports, zum Beispiel:

[{"scheme":"https","host":"git.example.com","ports":[443]}]

Verwenden Sie die endgültige Repository-URL ohne Weiterleitung, Zugangsdaten, Query oder Fragment. Lokale Pfade, SSH, IP-Adressen, CIDR-Regeln und Wildcards sind nicht zulässig. Das optionale Token gehört ausschließlich in das vorgesehene Token-Feld. Auch explizit freigegebene interne Hosts dürfen keine Loopback- oder Link-Local-Adressen auflösen. Workspace prüft alle DNS-Antworten und das TLS-Zertifikat des Hostnamens.

Die Freigabe wird nach einem Serverneustart wirksam; Werte einzelner Arbeitsbereiche ersetzen sie nicht. Ungültige globale Werte verhindern den Start. Prüfen Sie die Freigabe und den Neustart deshalb vor dem ersten Git-Deploy. Der Abruf einschließlich Verarbeitung und Checkout ist auf zehn Minuten und 100 MiB empfangene Git-Daten begrenzt, sein JSON-Request auf 64 KiB. Der Checkout darf höchstens 10.000 Einträge und insgesamt 512 MiB enthalten; jede Datei ist auf 32 MiB begrenzt. Symlinks werden abgewiesen.

Pro Serverprozess kann ein Git-Deploy laufen. Weitere Anfragen erhalten 503 ERR_GIT_BUSY; warten Sie bis zum Ende des laufenden Vorgangs. Der Git-Abruf benötigt die offizielle Nix- oder Container-Laufzeit für Linux mit Worker, Bubblewrap, CA-Bundle und durchsetzbaren Namespace-Grenzen. Native Tar-, Debian- und RPM-Pakete enthalten diese Nix-Store-Laufzeit nicht. Fehlt eine dieser Voraussetzungen, bleibt Workspace verfügbar; Git-Deploy liefert ohne schwächeren Fallback 503 ERR_GIT_UNAVAILABLE. Der Worker besitzt kein allgemeines IP-Netzwerk. Git-Metadaten und Checkout teilen eine feste 1-GiB-Arbeitsfläche. Zusätzlich gelten höchstens 2 GiB virtueller Adressraum und ein Speicherziel von 256 MiB; das Speicherziel ist keine garantierte Obergrenze für den physischen Speicherbedarf.

Bei Abbruch beendet Workspace Abrufprozess und Egress-Broker, bevor es temporäre Dateien entfernt. Der Worker kann höchstens vier rohe TCP-Verbindungen zur bereits geprüften und gepinnten Zieladresse öffnen. Nur reguläre Dateien, deren Pfad, Modus, Größe und Digest Workspace erneut geprüft hat, gelangen in das private Staging. Ein fehlgeschlagener Abruf lässt den bisherigen Quellstand unverändert. Für Fehler während der anschließenden Quellenübernahme besteht keine automatische Rücknahmegarantie. Ein erfolgreicher Vorgang liefert eine Release-ID; die Veröffentlichung bleibt ein separater Schritt. Die neue Sandbox-Laufzeit wird mit einem Serverneustart wirksam.

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.