Clerk CLI
Die clerk-Binärdatei ist ein vorauthentifiziertes Gateway zur Clerk Backend-API und Platform-API, sowie zu projektbezogenen Werkzeugen (Auth, Verknüpfung, Umgebungsvariablen-Pull, Instanzkonfiguration). Wenn der Benutzer etwas in Bezug auf eine Clerk-Ressource fragt, greife zuerst zu clerk, anstatt selbst curl zu bemühen.
Diese Fähigkeit zielt auf
clerk latest. Wennclerk --versionnicht mit der neuesten verfügbaren CLI übereinstimmt, aktualisiere sie mitclerk skill installoder einem Paket-Runner wiebunx clerk@latest. Die Binärdatei ist immer die Quelle der Wahrheit; führe daherclerk <command> --helpaus, um alle Angaben dieser Fähigkeit zu überprüfen.
Ausführungsumgebung (bevorzuge den Host, verstehe die Sandbox-Warnung)
Die meisten KI-Coding-Agenten führen Shell-Befehle standardmäßig in einer Sandbox aus, in der das Home-Verzeichnis des Benutzers, der OS-Keychain, das Starten des Browsers, der Localhost-Callback oder der Netzwerkzugriff blockiert sein können. Die Clerk CLI ist auf all diese Host-Funktionen angewiesen:
- OS-Anmeldeinformationsspeicher:
clerk auth loginspeichert das OAuth-Token im System-Keychain. Eine Sandbox ohne Keychain-Zugriff meldet „nicht eingeloggt“, selbst wenn der Host authentifiziert ist. - Clerk-Status im Home-Verzeichnis: gespeicherte Konfiguration, zwischengespeicherte Metadaten und Fallback-Anmeldeinformationen befinden sich in den Clerk-Konfigurations-/Datenverzeichnissen des Benutzers.
- Verknüpfte Projekt-Metadaten: aufgelöst aus dem Git-Remote des Repositorys und der Clerk-Konfiguration. Sandboxes mit reduziertem Repository-Status oder blockierten Home-Verzeichnis-Lesezugriffen können fälschlicherweise „nicht verknüpft“ melden.
- Lokale
.env*-Dateien: veröffentlichte und geheime Schlüssel, die vonclerk env pullmaterialisiert wurden. - Ausgehender Netzwerkzugriff zu Clerk: bei jedem Backend- und Platform-API-Aufruf.
- Browser + Localhost OAuth-Callback:
clerk auth loginbenötigt beides.
Im Agentenmodus führt die CLI jetzt eine Best-Effort-Einmal-Warnung an den host-sensitiven Bibliotheksgrenzen durch. Wenn sie erkennt, dass Host-only-Clerk-Status oder Systemfähigkeiten nicht verfügbar sind, gibt sie Folgendes aus:
Host-only-Clerk-Status oder Systemfähigkeiten sind im Agentenmodus möglicherweise nicht verfügbar. Dies könnte eine Sandbox-Umgebung sein.
Führe diesen Befehl erneut auf dem Host-Shell aus, bevor du Auth-, Link-, Env- oder API-Fehlern vertraust.
Behandle diese Warnung als autoritativ. Der Befehl kann fortgesetzt werden, aber alle Auth-, Link-, Env-, Config-, API-, Browser- oder OAuth-Callback-Fehler aus diesem Aufruf sind unzuverlässig, bis du denselben Befehl auf dem Host erneut ausführst.
Bevorzuge diese Befehle auf dem Host-Shell des Benutzers, nicht in einer Sandbox:
clerk doctor, clerk whoami, clerk auth login, clerk link, clerk env pull, clerk apps ..., clerk config ..., clerk api ....
Wenn ein Befehl versehentlich in einer Sandbox ausgeführt wurde und „Nicht eingeloggt“, auth_required, „nicht verknüpft“, fehlende Env-, Keychain-/Dateiberechtigungsfehler oder Netzwerkfehler meldet, behandle das Ergebnis nicht als autoritativ. Führe ihn auf dem Host erneut aus, bevor du darauf reagierst oder es dem Benutzer meldest.
Aufrufen der CLI
Bevor du einen clerk-Befehl ausführst, ermittle, welche Binärdatei aufgerufen werden soll, und binde diese Wahl für den Rest der Sitzung:
# 1. Bevorzuge eine global installierte Binärdatei, wenn sie der Zielversion der Fähigkeit entspricht.
command -v clerk >/dev/null 2>&1 && clerk --version
Wenn dies latest oder eine Version ausgibt, der du vertraust, verwende für den Rest der Sitzung clerk direkt.
Andernfalls falle auf einen Paket-Runner zurück, in dieser Reihenfolge (entspricht der preferredRunner-Logik der CLI, die den Runner bevorzugt, der zum Projekt-Lockfile passt):
| Projekt-Paketmanager | Aufruf |
|---|---|
bun (bun.lock*) | bunx clerk@latest |
npm (package-lock.json) | npx -y clerk@latest |
pnpm (pnpm-lock.yaml) | pnpm dlx clerk@latest |
yarn >= 2 (yarn.lock) | yarn dlx clerk@latest |
Yarn Classic (v1) hat kein dlx; behandle solche Projekte als „kein bevorzugter Runner“ und falle auf den ersten Runner aus der obigen Liste zurück, der im PATH ist.
Das veröffentlichte npm-Paket ist clerk, nicht @clerk/cli. Bringe niemals npm install -g clerk als primären Weg bei. Wenn die globale CLI veraltet ist oder sich anders verhält als diese Fähigkeit, aktualisiere entweder die globale Installation oder falle auf die obige latest-Runner-Form zurück.
Voraussetzungen (zu Sitzungsbeginn ausführen)
Bevor du in einer Sitzung einen anderen Clerk-Befehl ausführst, überprüfe, ob die CLI authentifiziert, verknüpft und fehlerfrei ist:
clerk --version # bestätige, dass die Binärdatei im PATH ist
clerk doctor --json # strukturierter Gesundheitscheck; exit 1 bei Fehlschlag
Führe immer zuerst clerk doctor --json aus. Es fängt die häufigsten Einrichtungsfehler (nicht eingeloggt, Projekt nicht verknüpft, fehlende Schlüssel, veraltete CLI-Version) frühzeitig ab, damit spätere Befehle nicht mit verwirrenden Fehlern fehlschlagen. Im Agentenmodus enthält es auch eine Host execution-Prüfung, die warnt, wenn die Clerk-Host-seitigen Konfigurations-/Anmeldeinformationsverzeichnisse nicht beschreibbar sind – das ist das kanonische Signal, dass der aktuelle Aufruf wahrscheinlich in einer Sandbox ist.
Jedes Ergebnis hat name, status (pass/warn/fail), message, optionales detail, optionales remedy (wie zu beheben) und optionales fix (Label für automatisch behebbare Probleme). Analysiere das und handle entsprechend oder zeige es dem Benutzer an. Wenn Host execution warnt, führe den Befehl auf dem Host erneut aus, bevor du Auth-/Link-/Env-/API-Fehlern aus derselben Sandbox-Sitzung vertraust. Führe clerk doctor --json erneut aus, wenn ein späterer Befehl sich falsch verhält.
Wenn clerk --version eine neuere CLI meldet, als diese Fähigkeit abdeckt, vertraue zuerst clerk <command> --help und aktualisiere dieses Fähigkeitsbündel von seiner Quelle.
Das mentale Modell
| Ebene | Was sie tut | Befehle |
|---|---|---|
| Sitzung / Projekt | Auth, verknüpfe ein Repository mit einer Clerk-App, ziehe Umgebungsvariablen | auth login, link, unlink, whoami, env pull, doctor |
| Instanzkonfiguration | Verwalte die Konfiguration (Social Provider, Sitzungslebensdauer usw.) für eine bestimmte Instanz | config pull, config schema, config patch, config put |
| Backend API (Standard) | Laufzeitdaten: Benutzer, Organisationen, Sitzungen, Einladungen, JWT-Vorlagen, Webhooks | clerk api <path> |
Platform API (--platform) | Kontoebene: Anwendungen, Instanzen, Abrechnung | clerk api --platform <path> |
Ein Projekt ist über clerk link mit einer Anwendung „verknüpft“. Nach der Verknüpfung lösen die meisten Befehle die Ziel-App und die Entwicklungsinstanz automatisch aus dem Git-Remote des Repositorys auf. Um etwas anderes anzusprechen, übergib --app <id> und/oder --instance dev|prod|<instance_id>. Siehe references/auth.md für die vollständige Auflösungsreihenfolge.
Entdecke Endpunkte – merke sie dir nicht
Die CLI wird mit dem Clerk OpenAPI-Katalog ausgeliefert. Entdecke Endpunkte immer dynamisch, anstatt Pfade zu raten:
clerk api ls # liste jeden Backend-API-Endpunkt auf
clerk api ls users # filtere nach Stichwort (stimmt mit Pfad, Zusammenfassung, Tag, operationId überein)
clerk api ls --platform apps # liste Platform-API-Endpunkte auf
Verwende dies vor clerk api <path>. Wenn du den erwarteten Endpunkt nicht siehst, ist er wahrscheinlich nicht verfügbar.
Der Befehl clerk api (das Arbeitstier)
clerk api führt authentifizierte HTTP-Aufrufe durch. Es löst automatisch Schlüssel auf, erkennt die Methode automatisch anhand des Vorhandenseins eines Bodys, unterstützt stdin und kann Mutationen mit --dry-run in der Vorschau anzeigen.
# GET-Anfragen
clerk api /users # Benutzer auflisten
clerk api /users/user_abc123 # einen abrufen
clerk api /users?limit=5&order_by=-created_at # Query-Parameter funktionieren inline
# Mutierende Anfragen
clerk api /users -d '{"email_address":["[email protected]"]}' # POST (automatisch aus Body erkannt)
clerk api /users/user_abc123 -X PATCH -d '{"first_name":"A"}'
clerk api /users/user_abc123 -X DELETE
# Body aus Datei oder stdin
clerk api /users --file payload.json
cat payload.json | clerk api /users
# Zeige Mutationen immer zuerst in der Vorschau an
clerk api /users/user_abc123 -X DELETE --dry-run
clerk api /users/user_abc123 -X DELETE --yes # überspringe Bestätigung, sobald du geprüft hast
# Ziel eine bestimmte App/Instanz
clerk api /users --app app_abc123 --instance prod
# Füge Antwort-Header beim Debuggen ein
clerk api /users --include
# Platform API (Kontoebene, nicht Mandantendaten)
clerk api /v1/platform/applications --platform
Bevorzuge für die Instanzkonfiguration die dedizierten clerk config ...-Befehle gegenüber rohen Platform-API /config-Pfaden. Sie handhaben Trockenlauf, Diffing und Bestätigung sauberer als die rohe Endpunkt-Form.
Führe bei Mutationen immer zuerst --dry-run aus, bevor du sie tatsächlich ausführst. Führe sie dann ohne --dry-run erneut aus (füge --yes hinzu, wenn du dir sicher bist). Im Agentenmodus wird die interaktive Bestätigung umgangen, daher ist --dry-run das einzige Sicherheitsnetz für zerstörerische Aufrufe.
JSON-Bodies müssen gültiges JSON sein. Die CLI validiert und lehnt fehlerhafte Nutzlasten ab.
Endpunkt-Pfade können mit oder ohne /v1/-Präfix angegeben werden – beide funktionieren für Backend-API-Aufrufe. Die CLI normalisiert.
Siehe references/recipes.md für konkrete Muster: Auflisten/Filtern von Benutzern, Erstellen von Organisationen, Impersonations-Sitzungen usw.
Große Ausgaben inspizieren (überflute deinen Kontext nicht)
users list, apps list, config pull und die meisten clerk api GETs geben Nutzlasten zurück, die viele Kilobyte oder Megabyte groß sein können. Produktionsmandanten haben oft Tausende von Benutzern; eine Instanzkonfiguration kann Hunderte von Feldern tief sein. Diese Antworten ins Gespräch zu lesen, kostet Kontextfenster ohne Nutzen. Speichere die Antwort zuerst in einer Datei und frage dann nur das ab, was du brauchst, mit jq:
# 1. Persistiere die Antwort. Verwende --limit 250, um die Seitengröße für die Benutzerliste zu maximieren.
clerk users list --json --limit 250 > /tmp/users.json
clerk apps list --json > /tmp/apps.json
clerk api /users/user_abc123 > /tmp/user.json
# 2. Inspiziere nur das Nötigste.
jq '.data | length' /tmp/users.json # aktuelle Seitengröße
jq '.hasMore' /tmp/users.json # sind weitere Seiten verfügbar?
jq '.data[0] | keys' /tmp/users.json # entdecke die Benutzerstruktur einmal
jq '.data[] | {id, email_addresses}' /tmp/users.json # projiziere auf wenige Felder
jq '[.data[] | select(.banned)] | length' /tmp/users.json # aggregiere ohne Zeilen zu lesen
Wenn jq nicht verfügbar ist, falle auf Python oder Node zurück – beide können die Datei streamen, ohne sie vollständig auszugeben:
python3 -c 'import json; d=json.load(open("/tmp/users.json")); print(len(d["data"]), d["hasMore"])'
node -e 'const d=require("/tmp/users.json"); console.log(d.data.length, d.hasMore)'
Verwende cat / head für die Datei nur, wenn du die rohe Struktur für einmaliges Debuggen wirklich sehen musst. Beim Durchlaufen von Seiten schreibe jede Seite in eine eigene Datei (z. B. page-${offset}.json), damit einzelne Seiten unabhängig inspizierbar bleiben.
Kernbefehle auf einen Blick
| Befehl | Zweck | Wichtige Flags |
|---|---|---|
clerk init | Clerk in ein Projekt einrichten. --starter unterstützt nur Bootstrap für Next.js, React Router, Astro, Nuxt, TanStack Start, React, Vue und JavaScript. | --framework, --pm, --name (mit --starter), --app, --starter, -y, --no-skills |
clerk auth login | OAuth-Browser-Login (speichert Token). Agentenmodus: No-op, wenn bereits eingeloggt. Ohne gespeicherte Sitzung öffnet es trotzdem einen Browser und bindet einen Localhost-Callback, daher nicht unbeaufsichtigt; bevorzuge CLERK_PLATFORM_API_KEY für Headless-Abläufe. Aliase: signup, signin, sign-in. Kurzform auf oberster Ebene: clerk login. | - |
clerk auth logout | Gespeicherte Anmeldeinformationen löschen. Aliase: signout, sign-out. Kurzform auf oberster Ebene: clerk logout. | - |
clerk whoami | Die eingeloggte E-Mail ausgeben. | - |
...