Clerk CLI

Le binaire clerk est une passerelle pré-authentifiée vers l'API Backend et l'API Platform de Clerk, plus des outils au niveau du projet (auth, linking, env pulls, config d'instance). Quand l'utilisateur demande quelque chose qui touche une ressource Clerk, utilise d'abord clerk plutôt que de construire des appels curl à la main.

Cette compétence cible clerk latest. Si clerk --version diffère de la dernière CLI disponible, rafraîchis-la avec clerk skill install ou un gestionnaire de paquets comme bunx clerk@latest. Le binaire est toujours la source de vérité, donc exécute clerk <command> --help pour vérifier tout ce que cette compétence affirme.

Environnement d'exécution (préfère le host, comprends l'avertissement sandbox)

La plupart des agents de codage IA exécutent par défaut les commandes shell dans un sandbox où le répertoire home de l'utilisateur, le trousseau du système, le lancement du navigateur, la liaison localhost callback, ou l'accès réseau peuvent être bloqués. Le CLI Clerk dépend de toutes ces capacités du host :

• Magasin de credentials du système : clerk auth login stocke le token OAuth dans le trousseau système. Un sandbox sans accès au trousseau rapporte "pas connecté" même quand le host est authentifié.
• État Clerk du répertoire home : config sauvegardée, métadonnées en cache et credentials de secours vivent sous les répertoires config/data Clerk de l'utilisateur.
• Métadonnées de projet lié : résolues depuis le remote git du repo plus la config Clerk. Les sandboxes avec état de repo dépouillé ou lectures home-dir bloquées peuvent rapporter incorrectement "non lié".
• *Fichiers `.envlocaux** : clés publiables et secrètes matérialisées parclerk env pull`.
• Accès réseau sortant à Clerk : chaque appel Backend et Platform API.
• Browser + localhost OAuth callback : clerk auth login a besoin de tous deux.

En mode agent, le CLI fait maintenant une vérification d'avertissement best-effort une fois aux limites de la bibliothèque sensibles au host. Quand il détecte que l'état Clerk côté host ou les capacités système sont indisponibles, il émet :

Host-only Clerk state or system capabilities may be unavailable in agent mode. This may be a sandboxed run.
Re-run this command on the host shell before trusting auth, link, env, or API failures.

Traite cet avertissement comme autoritaire. La commande peut continuer, mais tout échec auth, link, env, config, API, browser ou OAuth callback de cette invocation est non fiable jusqu'à ce que tu réexécutes la même commande sur le host.

Préfère ces commandes sur le shell host 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 elle rapporte Not logged in, auth_required, not linked, env manquant, erreurs de permission keychain/fichier, ou défaillances réseau, ne traite pas le résultat comme autoritaire. Réexécute-la sur le host avant d'agir dessus ou de le rapporter à l'utilisateur.

Invoquer le CLI

Avant d'exécuter une commande clerk, détermine quel binaire invoquer et lie ce choix pour le reste de la session :

# 1. Préfère un binaire installé globalement quand il correspond à la version cible de la compétence.
command -v clerk >/dev/null 2>&1 && clerk --version

Si cela affiche latest ou une version en laquelle tu as confiance, utilise clerk nu pour le reste de la session.

Sinon, bascule vers un gestionnaire de paquets, dans cet ordre (correspond à la logique preferredRunner du CLI lui-même, qui préfère le gestionnaire qui correspond au lockfile du projet) :

Yarn Classic (v1) n'a pas de dlx ; traite ces projets comme "pas de gestionnaire préféré" et bascule vers le premier gestionnaire de la liste ci-dessus qui est sur PATH.

Le paquet npm publié est clerk, pas @clerk/cli. N'enseigne jamais npm install -g clerk comme chemin principal. Si le CLI global est obsolète ou se comporte différemment de cette compétence, soit mets à jour l'installation globale, soit bascule vers la forme latest du runner ci-dessus.

Prérequis (exécute au démarrage de la session)

Avant d'exécuter toute autre commande Clerk dans une session, vérifie que le CLI est authentifié, lié et en bonne santé :

clerk --version               # confirme que le binaire est sur PATH
clerk doctor --json           # vérification structurée de la santé ; exit 1 si quelque chose a échoué

Exécute toujours clerk doctor --json en premier. Cela capture les défaillances de configuration courantes (pas connecté, projet non lié, clés manquantes, version CLI obsolète) d'emblée, pour que les commandes ultérieures ne échouent pas avec des erreurs déroutantes. En mode agent, cela inclut aussi une vérification Host execution qui avertit quand les répertoires config/credentials côté host de Clerk ne sont pas accessibles en écriture, ce qui est le signal canonique que l'invocation actuelle est probablement sandboxée.

Chaque résultat a name, status (pass/warn/fail), message, detail optionnel, remedy optionnel (comment le corriger), et fix optionnel (label pour les problèmes auto-réparables). Analyse cela et agis dessus, ou expose-le à l'utilisateur. Si Host execution avertit, réexécute la commande sur le host avant de faire confiance à tout échec auth/link/env/API de la même exécution sandboxée. Réexécute clerk doctor --json chaque fois qu'une commande ultérieure commence à mal se comporter.

Si clerk --version rapporte un CLI plus récent que celui que cette compétence couvre, fais confiance à clerk <command> --help en premier et rafraîchis ce bundle de compétence depuis sa source.

Le modèle mental

Un projet est "lié" à une application via clerk link. Une fois lié, la plupart des commandes résolvent automatiquement l'app cible et l'instance dev depuis le remote git du repo. Pour cibler quelque chose d'autre, passe --app <id> et/ou --instance dev|prod|<instance_id>. Vois references/auth.md pour l'ordre de résolution complet.

Découvre les endpoints - ne les mémorise pas

Le CLI est livré avec le catalogue OpenAPI de Clerk. Découvre toujours les endpoints dynamiquement plutôt que de deviner les chemins :

clerk api ls                  # liste tous les endpoints Backend API
clerk api ls users            # filtre par mot-clé (correspond chemin, résumé, tag, operationId)
clerk api ls --platform apps  # liste les endpoints Platform API

Utilise cela avant clerk api <path>. Si tu ne vois pas l'endpoint que tu t'attendais, il n'est probablement pas exposé.

La commande clerk api (le workhorse)

clerk api fait des appels HTTP authentifiés. Il résout auto les clés, auto-détecte la méthode depuis la présence du corps, supporte stdin, et peut prévisualiser les mutations avec --dry-run.

# Requêtes GET
clerk api /users                                  # lister les utilisateurs
clerk api /users/user_abc123                      # en chercher un
clerk api /users?limit=5&order_by=-created_at     # les params query fonctionnent inline

# Requêtes mutantes
clerk api /users -d '{"email_address":["a@b.co"]}'          # POST (auto-détecté du corps)
clerk api /users/user_abc123 -X PATCH -d '{"first_name":"A"}'
clerk api /users/user_abc123 -X DELETE

# Corps depuis un fichier ou stdin
clerk api /users --file payload.json
cat payload.json | clerk api /users

# Prévisualise toujours les mutations d'abord
clerk api /users/user_abc123 -X DELETE --dry-run
clerk api /users/user_abc123 -X DELETE --yes      # saute la confirmation une fois que tu as vérifié

# Cible une app/instance spécifique
clerk api /users --app app_abc123 --instance prod

# Inclus les headers de réponse pour déboguer
clerk api /users --include

# API Platform (niveau compte, pas données tenant)
clerk api /v1/platform/applications --platform

Pour la config d'instance, préfère les commandes dédiées clerk config ... aux chemins raw Platform API /config. Elles gèrent dry-run, diffing et confirmation plus proprement que la forme raw endpoint.

Exécute toujours --dry-run une mutation avant de la lancer pour de vrai. Puis réexécute sans --dry-run (ajoute --yes si tu es sûr). En mode agent, la confirmation interactive est contournée, donc --dry-run est le seul filet de sécurité pour les appels destructifs.

Les corps JSON doivent être du JSON valide. Le CLI valide et rejette les payloads mal formées.

Les chemins d'endpoint peuvent être donnés avec ou sans préfixe /v1/ - les deux fonctionnent pour les appels Backend API. Le CLI normalise.

Vois references/recipes.md pour des motifs concrets : lister/filtrer les utilisateurs, créer des orgs, sessions d'emprunt d'identité, etc.

Inspecter les sorties volumineuses (ne noie pas ton contexte)

users list, apps list, config pull, et la plupart des clerk api GETs retournent des payloads qui peuvent faire plusieurs kilooctets ou mégaoctets. Les tenants de production ont couramment des milliers d'utilisateurs ; une config d'instance peut être des centaines de champs de profondeur. Lire ces réponses dans la conversation coûte context window sans bénéfice. Sauvegarde la réponse dans un fichier d'abord, puis interroge juste ce dont tu as besoin avec jq :

# 1. Persiste la réponse. Utilise --limit 250 pour maximiser la taille de page pour users list.
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. Inspecte seulement ce que tu as besoin.
jq '.data | length'                       /tmp/users.json   # taille de page actuelle
jq '.hasMore'                             /tmp/users.json   # y a-t-il plus de pages ?
jq '.data[0] | keys'                      /tmp/users.json   # découvre la forme utilisateur une fois
jq '.data[] | {id, email_addresses}'      /tmp/users.json   # projette vers quelques champs
jq '[.data[] | select(.banned)] | length' /tmp/users.json   # agrège sans lire les lignes

Si jq n'est pas disponible, bascule vers Python ou Node - tous deux peuvent streamer le fichier sans l'afficher intégralement :

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)'

cat / head le fichier seulement quand tu as vraiment besoin de voir la structure brute pour déboguer ponctuellement. Quand tu marches dans les pages, écris chaque page dans son propre fichier (ex. page-${offset}.json) pour que les pages individuelles restent indépendamment inspectables.

Commandes principales en un coup d'œil

clerk <command> --help est la source de vérité pour les flags. Ce tableau est un indice, pas une spécification. Avant d'exécuter une combinaison de commande ou flag non familière, exécute clerk <command> --help une fois par session. Chaque commande définit aussi setExamples([...]) en source, que --help rend comme un bloc Examples copiable-collable, donc tu dois rarement deviner la syntaxe.

Comportement mode agent (important)

Le CLI auto-détecte le mode agent quand stdout n'est pas un TTY, ou quand --mode agent / CLERK_MODE=agent est défini. En mode agent :

• Les prompts interactifs sont désactivés. Les commandes qui montreraient normalement des pickers (link sans --app, unlink sans --yes, users sans sous-commande) soit résolvent auto, soit sortent avec une erreur d'utilisation. clerk api sans args affiche un guide d'utilisation et sort 0 ; passe un endpoint (ou ls) explicitement. Passe toujours des flags explicites (--app, --yes) dans les appels scriptés.
• Les opérations sensibles au host émettent un avertissement sandbox une fois par invocation. L'état Clerk home-directory, l'accès au trousseau, les appels Clerk en réseau, le lancement du navigateur et la configuration du callback localhost OAuth peuvent déclencher l'avertissement montré ci-dessus. S'il apparaît, réexécute la même commande sur le host avant de faire confiance au résultat.
• Si ton harnais ne se présente pas clairement comme mode agent, force-le. Utilise --mode agent ou CLERK_MODE=agent quand tu veux que le comportement non-interactif du CLI et le chemin d'avertissement sandbox s'appliquent de manière déterministe.
• link supporte les flux agent déterministes. En mode agent, clerk link --app <id> lie directement. Sans --app, le CLI essayera d'abord un autolink basé clé silencieux ; s'il ne peut pas déterminer l'app sans ambiguïté, il sort et te dit de passer --app.
• init ne sélectionne ou crée jamais une véritable app Clerk pour toi en mode agent à moins d'être authentifié ou donné une cible. Passe --app <id> (ou pré-lie le projet) pour authentifier et lier une véritable app, ou passe --keyless pour utiliser les clés de développement temporaires auto-générées quand tu bootstrapes un nouveau projet sur un framework compatible keyless. Sans l'un ou l'autre, le mode agent affiche un guide de configuration manuel et sort proprement.
• unlink requiert --yes en mode agent. Cela préserve la même barre de sécurité que d'autres commandes destructives tout en permettant à un agent de terminer l'unlink non-interactivement.
• Les mutations requièrent toujours --yes sauf si tu acceptes que la confirmation par appel soit impossible.
• doctor --fix est ignoré. Analyse le champ remedy de la sortie doctor --json et agis dessus toi-même.
• apps list et apps create par défaut JSON quand pipelined.
• users par défaut JSON quand pipelined, comme apps. clerk users list et clerk users create émettent JSON en mode agent. clerk users nu (pas de sous-commande) est une erreur d'utilisation en mode agent - passe list, create ou open explicitement. clerk users open requiert le positional user-id en mode agent et affiche un descripteur JSON au lieu de lancer un navigateur.
• deploy a un handoff agent plus une porte de vérification. En mode agent, clerk deploy nu est read-only et émet un handoff JSON. Il ne pilote jamais l'assistant interactif. Ne dis pas à Claude ou un autre agent d'exécuter ! clerk deploy, car l'assistant a besoin de prompts stdin interactifs. Demande au humain d'exécuter clerk deploy dans une nouvelle fenêtre terminal quand nécessaire, puis exécute clerk deploy status --mode agent pour vérifier l'achèvement. Vois references/agent-mode.md.
• --input-json <json|@file|-> développe JSON en flags sur toute commande (ex. clerk init --input-json '{"framework":"next","yes":true}'). Stdin pipelined est aussi accepté : echo '{"yes":true}' | clerk init. Place --input-json après la sous-commande leaf. Règles complètes dans references/agent-mode.md.

Matrice complète et détails sandbox dans references/agent-mode.md.

Format de sortie et erreurs

• Sortie JSON : --json sur apps list et doctor. Pour clerk api, le corps de réponse est le JSON API brut, donc pipe dans jq librement.
• Codes de sortie : 0 succès, 1 erreur runtime, 2 erreur d'utilisation/validation. doctor retourne 1 si toute vérification a échoué.
• Format d'erreur : Les erreurs visibles utilisateur affichent une seule ligne sur stderr et définissent un code de sortie non-zéro. Utilise --verbose pour les stack traces quand tu débogues.

Règles de sécurité pour utilisation autonome

1. Découvre avant d'agir : clerk api ls <keyword> avant clerk api <path>.
2. Prévisualise les mutations : --dry-run sur chaque config patch, config put, api -X POST/PATCH/PUT/DELETE.
3. Cible explicitement en production : passe --instance prod plutôt que de compter sur les defaults, et confirme avec l'utilisateur avant toute mutation de production.
4. Ne committe jamais de secrets : env pull écrit dans .env.local (qui devrait être gitignored). Ne colle pas les clés secrètes dans le code ou le chat.
5. Utilise doctor --json pour diagnostiquer avant de supposer que le CLI est cassé.

Références

• references/auth.md - flux auth, ordre de résolution des clés, comportement host-vs-sandbox, ciblage --app/--instance, Backend vs Platform API.
• references/recipes.md - recettes copiables-collables pour tâches Clerk courantes.
• references/agent-mode.md - matrice comportement mode agent, sémantique d'avertissement sandbox, codes de sortie, format d'erreur.