CLI und API

Entwickler nutzen Workspace-APIs, um eigene Anwendungen, Integrationen, Websites und Automationen zu bauen. nucli ist das passende Werkzeug, wenn Sie Schnittstellen erkunden und API-Aufrufe reproduzierbar testen wollen.

nucli spricht HTTP gegen eine laufende Workspace-Instanz. Es liest keine Serverkonfiguration, greift nicht direkt auf Datenbanken zu und nutzt für authentifizierte Aufrufe den angemeldeten Workspace-Kontext.

Einstieg

Beginnen Sie mit der Discovery-API. Sie zeigt, welche Einstiegspunkte eine Workspace-Instanz veröffentlicht:

GET/api/v1/meta/discovery

nucli --host https://workspace.example discovery
nucli --host https://workspace.example api --anonymous GET /api/v1/meta/discovery --summary

Wenn ein Endpunkt eine Anmeldung braucht, melden Sie sich zuerst an:

nucli --host https://workspace.example login --email <email>
nucli api GET /api/v1/profile/entrypoints --summary

Für Skripte lesen Sie das Passwort über stdin und wählen bei mehreren Mandanten den erwarteten Tenant explizit:

printf '%s\n' "$WORKSPACE_PASSWORD" \
  | nucli --host https://workspace.example --tenant <tenant> --tenant-id <tenant-id> \
      login --email <email> --password-stdin --otp "$WORKSPACE_OTP"

nucli login verwendet den Headless-Auth-Vertrag. Es speichert kein Passwort. Für kurzlebige CI- oder Automationsläufe kann ein Prozess-Token über die Umgebung bereitstehen; nucli persistiert diesen Wert nicht.

Mit nucli profiles use <alias> setzen Sie einen lokalen Tenant-Alias als Standardprofil für nachfolgende Befehle ohne --tenant.

Ressourcen entdecken

Nutzen Sie Ressourcenlisten, bevor Sie konkrete IDs in Skripte übernehmen:

nucli --tenant <tenant> resources list
nucli --tenant <tenant> resources meta <entrypoint-id>
nucli --tenant <tenant> resources get <entrypoint-id>

Für Änderungen nutzen Sie nur Aktionen, die der Server in resources meta veröffentlicht:

nucli --tenant <tenant> resources create <entrypoint-id> --input payload.json --summary
nucli --tenant <tenant> resources update <entrypoint-id> <id> --input payload.json --summary
nucli --tenant <tenant> resources patch <entrypoint-id> <id> --input patch.json --summary
nucli --tenant <tenant> resources delete <entrypoint-id> <id> --summary

resources get <entrypoint-id> --all --max-pages <n> sammelt paginierte Listen begrenzt ein. Für Einzelobjekte ist --all nicht erlaubt.

Kontext prüfen

Prüfen Sie vor mutierenden API-Aufrufen den ausgewählten Kontext:

nucli --tenant <tenant> whoami
nucli --tenant <tenant> whoami --scopes
nucli --tenant <tenant> scopes

whoami zeigt Profil, Host, Tenant-Alias, aktive Tenant-ID und ob eine Session verfügbar ist. Es gibt keine Personendaten, Tokenwerte, Cookie-Werte oder Tokenquellen aus.

Nutzen Sie doctor, wenn Sie Host, Profil, Tokenstore, Session, Tenant-Guard und Discovery prüfen wollen:

nucli --tenant <tenant> doctor
nucli --tenant <tenant> doctor --json

diagnose liest tenantgebundene Diagnosewerte aus einem angemeldeten Kontext und gibt nur kuratierte Status- und Zählwerte aus:

nucli --tenant <tenant> diagnose --json
nucli diagnose --all-tenants --json

API-Aufrufe protokollieren

Für reproduzierbare Fehlersuche speichern Sie Antworten in Dateien und reduzieren die Konsolenausgabe:

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

GET/api/v1/meta/privacy

--summary gibt nur Metadaten wie Methode, URL, Status, Content-Type, Größe und Request-ID aus. --redact maskiert bekannte sensible JSON-Felder und bricht bei Nicht-JSON-Antworten ab, ohne den Raw-Body auszugeben.

--save schreibt den Body mit eingeschränkten Dateirechten. Kombinieren Sie --save und --redact, wenn eine Antwort Personen-, Kontakt-, Token-, Adress-, IBAN- oder BIC-Felder enthalten kann. Query-Parameter mit sensiblen Namen werden in Summary-URLs maskiert.

Für paginierte GET-Listen kann nucli Seiten begrenzt einsammeln:

nucli --tenant <tenant> api GET /api/v1/import-jobs --all --max-pages 5 --summary

--all folgt meta.pagination.nextOffset, setzt ohne vorhandenen count- oder limit-Parameter count=100 und markiert das Ergebnis als truncated, wenn --max-pages erreicht ist.

Privacy-Felder prüfen

Nutzen Sie den Privacy-Katalog, bevor Sie Felder in Exporten oder Fehlersuche-Artefakten verwenden:

nucli --host https://workspace.example privacy --json
nucli privacy --file openapi.json --path /api/v1/contacts --json
nucli privacy --file openapi.json --category contact.email
nucli privacy --file openapi.json --classification personal

Der Serververtrag veröffentlicht nur Felder mit expliziter Privacy-Metadatenannotation. Ein leerer Treffer bedeutet nicht, dass eine fachliche Antwort frei von Personen- oder Geschäftsdaten ist.

Browser-Ansicht

Öffnen Sie einfache GET-Endpunkte im Browser, wenn Sie die Browser-Session prüfen wollen:

nucli --host https://workspace.example discovery --web
nucli api --web /api/v1/meta/discovery

--web führt keinen HTTP-Aufruf aus nucli heraus aus. Der Browser nutzt seine eigenen Cookies. Deshalb akzeptiert nucli api --web nur GET-Aufrufe ohne Body und ohne eigene Header.

Mehrere Implementierungen dokumentieren

Wenn Sie Anwendungsbeispiele schreiben, zeigen Sie die gleiche Aufgabe pro Sprache oder Werkzeug in Tabs:

curl -s https://workspace.example/api/v1/meta/discovery

nucli api GET /api/v1/meta/discovery --anonymous --summary