CLI Clerk
Le binaire clerk est une passerelle pré-authentifiée vers l'API Backend et l'API Platform de Clerk, ainsi que des outils au niveau du projet (authentification, liaison, extraction de variables d'environnement, configuration d'instance). Lorsque l'utilisateur demande quelque chose qui touche à une ressource Clerk, utilisez clerk en premier lieu plutôt que de faire du curl à la main.
Cette compétence cible la version
latestde clerk. Siclerk --versionne correspond pas à la dernière version disponible de la CLI, actualisez-la avecclerk skill installou un exécuteur de paquets tel quebunx clerk@latest. Le binaire est toujours la source de vérité, exécutez doncclerk <commande> --helppour vérifier tout ce que cette compétence prétend.
Environnement d'exécution (privilégiez l'hôte, comprenez l'avertissement du sandbox)
La plupart des agents de codage IA exécutent par défaut les commandes shell dans un sandbox où le répertoire personnel de l'utilisateur, le trousseau système, le lancement du navigateur, la liaison de rappel localhost ou l'accès réseau peuvent être bloqués. La CLI Clerk dépend de toutes ces capacités de l'hôte :
- Stockage des identifiants du système d'exploitation :
clerk auth loginstocke le jeton OAuth dans le trousseau système. Un sandbox sans accès au trousseau signale 'non connecté' même lorsque l'hôte est authentifié. - État Clerk du répertoire personnel : la configuration sauvegardée, les métadonnées mises en cache et les identifiants de secours se trouvent dans les répertoires de configuration/données Clerk de l'utilisateur.
- Métadonnées du projet lié : résolues à partir du dépôt Git distant du projet plus la configuration Clerk. Les sandbox avec un état de dépôt réduit ou un accès au répertoire personnel bloqué peuvent signaler à tort 'non lié'.
- Fichiers
.env*locaux : clés publiables et secrètes matérialisées parclerk env pull. - Accès réseau sortant vers Clerk : chaque appel à l'API Backend et Platform.
- Rappel OAuth navigateur + localhost :
clerk auth logina besoin des deux.
En mode agent, la CLI effectue maintenant une vérification unique de meilleur effort avec avertissement aux frontières des bibliothèques sensibles de l'hôte. Lorsqu'elle détecte que l'état Clerk exclusif à l'hôte ou les capacités système ne sont pas disponibles, elle émet :
L'état Clerk exclusif à l'hôte ou les capacités système peuvent ne pas être disponibles en mode agent. Il peut s'agir d'une exécution en sandbox.
Réexécutez cette commande sur le shell hôte avant de faire confiance aux échecs d'authentification, de liaison, d'environnement ou d'API.
Considérez cet avertissement comme faisant autorité. La commande peut continuer, mais tout échec d'authentification, de liaison, d'environnement, de configuration, d'API, de navigateur ou de rappel OAuth résultant de cette invocation n'est pas fiable tant que vous n'avez pas réexécuté la même commande sur l'hôte.
Privilégiez ces commandes sur le shell hôte de l'utilisateur, pas dans un sandbox :
clerk doctor, clerk whoami, clerk auth login, clerk link, clerk env pull, clerk apps ..., clerk config ..., clerk api ....
Si une commande a été accidentellement exécutée dans un sandbox et qu'elle signale 'Non connecté', auth_required, 'non lié', des variables d'environnement manquantes, des erreurs de permission de fichier/trousseau ou des échecs réseau, ne traitez pas le résultat comme faisant autorité. Réexécutez-la sur l'hôte avant d'agir en conséquence ou de la signaler à l'utilisateur.
Invoquer la CLI
Avant d'exécuter une commande clerk, déterminez quel binaire invoquer et fixez ce choix pour le reste de la session :
# 1. Privilégiez un binaire installé globalement s'il correspond à la version cible de la compétence.
command -v clerk >/dev/null 2>&1 && clerk --version
Si cela affiche latest ou toute version en laquelle vous avez confiance, utilisez clerk nu pour le reste de la session.
Sinon, utilisez un exécuteur de paquets, dans cet ordre (correspond à la logique preferredRunner propre de la CLI, qui privilégie l'exécuteur correspondant au fichier lock du projet) :
| Gestionnaire de paquets du projet | Invocation |
|---|---|
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) n'a pas de dlx ; traitez ces projets comme 'aucun exécuteur privilégié' et utilisez le premier exécuteur de la liste ci-dessus qui se trouve dans le PATH.
Le paquet npm publié est clerk, pas @clerk/cli. N'enseignez jamais npm install -g clerk comme chemin principal. Si la CLI globale est obsolète ou se comporte différemment de cette compétence, soit mettez à jour l'installation globale, soit utilisez la forme d'exécuteur latest ci-dessus.
Prérequis (exécutés au début de la session)
Avant d'exécuter toute autre commande Clerk dans une session, vérifiez que la CLI est authentifiée, liée et saine :
clerk --version # confirmer que le binaire est dans le PATH
clerk doctor --json # vérification de santé structurée ; quitte avec le code 1 si quelque chose a échoué
Exécutez toujours clerk doctor --json en premier. Cela détecte les problèmes de configuration courants (non connecté, projet non lié, clés manquantes, version CLI obsolète) en amont, afin que les commandes ultérieures n'échouent pas avec des erreurs déroutantes. En mode agent, il inclut également une vérification Exécution sur l'hôte qui avertit lorsque les répertoires de configuration/d'identifiants côté hôte de Clerk ne sont pas accessibles en écriture, ce qui est le signal canonique que l'invocation actuelle est probablement en sandbox.
Chaque résultat a name, status (pass/warn/fail), message, detail (optionnel), remedy (optionnel, comment le réparer) et fix (optionnel, étiquette pour les problèmes auto-réparables). Analysez cela et agissez en conséquence, ou présentez-le à l'utilisateur. Si Exécution sur l'hôte émet un avertissement, réexécutez la commande sur l'hôte avant de faire confiance à tout échec d'authentification/liaison/environnement/API provenant de la même exécution en sandbox. Réexécutez clerk doctor --json chaque fois qu'une commande ultérieure commence à mal se comporter.
Si clerk --version signale une CLI plus récente que celle couverte par cette compétence, faites d'abord confiance à clerk <commande> --help et actualisez ce bundle de compétence à partir de sa source.
Le modèle mental
| Couche | Ce qu'elle fait | Commandes |
|---|---|---|
| Session / projet | Authentification, lier un dépôt à une application Clerk, extraire les clés d'environnement | auth login, link, unlink, whoami, env pull, doctor |
| Configuration d'instance | Gérer la configuration (fournisseurs sociaux, durées de session, etc.) pour une instance spécifique | config pull, config schema, config patch, config put |
| API Backend (par défaut) | Données d'exécution : utilisateurs, organisations, sessions, invitations, modèles JWT, webhooks | clerk api <chemin> |
API Platform (--platform) | Au niveau du compte : applications, instances, facturation | clerk api --platform <chemin> |
Un projet est 'lié' à une application via clerk link. Une fois lié, la plupart des commandes résolvent automatiquement l'application cible et l'instance de développement à partir du dépôt Git distant du projet. Pour cibler autre chose, passez --app <id> et/ou --instance dev|prod|<instance_id>. Voir references/auth.md pour l'ordre de résolution complet.
Découvrir les points de terminaison – ne les mémorisez pas
La CLI est livrée avec le catalogue OpenAPI de Clerk. Découvrez toujours les points de terminaison dynamiquement au lieu de deviner les chemins :
clerk api ls # lister chaque point de terminaison de l'API Backend
clerk api ls users # filtrer par mot-clé (correspond au chemin, résumé, balise, operationId)
clerk api ls --platform apps # lister les points de terminaison de l'API Platform
Utilisez ceci avant clerk api <chemin>. Si vous ne voyez pas le point de terminaison attendu, il n'est probablement pas exposé.
La commande clerk api (le cheval de bataille)
clerk api effectue des appels HTTP authentifiés. Elle résout automatiquement les clés, détecte automatiquement la méthode à partir de la présence du corps, prend en charge l'entrée standard et peut prévisualiser les mutations avec --dry-run.
# Requêtes GET
clerk api /users # lister les utilisateurs
clerk api /users/user_abc123 # en récupérer un
clerk api /users?limit=5&order_by=-created_at # les paramètres de requête fonctionnent en ligne
# Requêtes de mutation
clerk api /users -d '{"email_address":["[email protected]"]}' # POST (détecté automatiquement à partir du corps)
clerk api /users/user_abc123 -X PATCH -d '{"first_name":"A"}'
clerk api /users/user_abc123 -X DELETE
# Corps à partir d'un fichier ou de l'entrée standard
clerk api /users --file payload.json
cat payload.json | clerk api /users
# Toujours prévisualiser les mutations en premier
clerk api /users/user_abc123 -X DELETE --dry-run
clerk api /users/user_abc123 -X DELETE --yes # sauter la confirmation une fois que vous avez vérifié
# Cibler une application/instance spécifique
clerk api /users --app app_abc123 --instance prod
# Inclure les en-têtes de réponse lors du débogage
clerk api /users --include
# API Platform (au niveau du compte, pas les données du locataire)
clerk api /v1/platform/applications --platform
Pour la configuration d'instance, privilégiez les commandes dédiées clerk config ... plutôt que les chemins bruts de l'API Platform /config. Elles gèrent le dry-run, le diff et la confirmation plus proprement que la forme de point de terminaison brut.
Faites toujours un --dry-run d'une mutation avant de l'exécuter pour de vrai. Réexécutez-la ensuite sans --dry-run (ajoutez --yes si vous êtes sûr). En mode agent, la confirmation interactive est contournée, donc --dry-run est le seul filet de sécurité pour les appels destructeurs.
Les corps JSON doivent être du JSON valide. La CLI valide et rejette les charges utiles malformées.
Les chemins de point de terminaison peuvent être donnés avec ou sans le préfixe /v1/ – les deux fonctionnent pour les appels à l'API Backend. La CLI normalise.
Voir references/recipes.md pour des modèles concrets : lister/filtrer les utilisateurs, créer des organisations, des sessions d'usurpation d'identité, etc.
Inspecter les résultats volumineux (ne saturez pas votre contexte)
users list, apps list, config pull et la plupart des GET de clerk api renvoient des charges utiles qui peuvent faire plusieurs kilo-octets ou méga-octets. Les locataires de production ont couramment des milliers d'utilisateurs ; une configuration d'instance peut avoir des centaines de champs. Lire ces réponses dans la conversation coûte de l'espace de contexte pour aucun bénéfice. Sauvegardez d'abord la réponse dans un fichier, puis interrogez uniquement ce dont vous avez besoin avec jq :
# 1. Persistez la réponse. Utilisez --limit 250 pour maximiser la taille de page pour la liste des utilisateurs.
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. Inspectez uniquement ce dont vous avez besoin.
jq '.data | length' /tmp/users.json # taille de la page actuelle
jq '.hasMore' /tmp/users.json # y a-t-il plus de pages disponibles ?
jq '.data[0] | keys' /tmp/users.json # découvrir la forme de l'utilisateur une fois
jq '.data[] | {id, email_addresses}' /tmp/users.json # projeter sur quelques champs
jq '[.data[] | select(.banned)] | length' /tmp/users.json # agréger sans lire les lignes
Si jq n'est pas disponible, utilisez Python ou Node – les deux peuvent lire le fichier en flux sans l'imprimer en entier :
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)'
Utilisez cat / head sur le fichier uniquement lorsque vous avez vraiment besoin de voir la structure brute pour un débogage ponctuel. Lorsque vous parcourez les pages, écrivez chaque page dans son propre fichier (par exemple page-${offset}.json) afin que les pages individuelles restent inspectables indépendamment.
Commandes essentielles en un coup d'œil
| Commande | Objectif | Principaux indicateurs |
|---|---|---|
clerk init | Intégrer Clerk dans un projet. --starter ne prend en charge que le bootstrap pour Next.js, React Router, Astro, Nuxt, TanStack Start, React, Vue et JavaScript. | --framework, --pm, --name (avec --starter), --app, --starter, -y, --no-skills |
clerk auth login | Connexion navigateur OAuth (stocke le jeton). Mode agent : sans opération si déjà connecté. Sans session stockée, il ouvre toujours un navigateur et lie un rappel localhost, donc il n'est pas automatisé ; préférez CLERK_PLATFORM_API_KEY pour les flux sans intervention. Alias : signup, signin, sign-in. Raccourci de premier niveau : clerk login. | - |
clerk auth logout | Effacer les identifiants stockés. Alias : signout, sign-out. Raccourci de premier niveau : clerk logout. | - |
clerk whoami | Afficher l'e-mail de l'utilisateur connecté. | - |
…
[Note : Le contenu a été tronqué pour la traduction. La compétence complète documente en détail la CLI Clerk, son environnement d'exécution, son invocation, ses prérequis, son modèle mental, la découverte des points de terminaison, l'inspection des résultats volumineux et les commandes essentielles, conformément à la spécification SKILL.md originale.]