Clerk CLI

Le binaire clerk est une passerelle pré-authentifiée vers les APIs Backend et Platform de Clerk, ainsi que des outils au niveau du projet (auth, linking, env pulls, instance config). Quand l'utilisateur demande quelque chose qui touche une ressource Clerk, utilisez clerk en priorité au lieu de rouler des curl manuels.

Pour les requêtes setup ou init, utilisez la skill clerk-setup comme source de vérité. Son package-runner, approche accountless, guidance migration et init-first prennent la priorité sur les prérequis opérationnels généraux ci-dessous.

Cette skill cible clerk latest. Si clerk --version diffère de la dernière version CLI disponible, rafraîchissez-la avec clerk update, ou invoquez la dernière via un package runner tel que bunx clerk@latest. Le binaire est toujours la source de vérité, donc lancez clerk <command> --help pour vérifier tout ce que cette skill affirme.

Environnement d'exécution (préférer l'hôte, comprendre 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 keychain OS, le lancement du navigateur, la liaison du callback localhost, ou l'accès réseau peuvent être bloqués. Le CLI Clerk dépend de toutes ces capacités hôte :

• Magasin d'identifiants OS : clerk auth login stocke le token OAuth dans le keychain système. Un sandbox sans accès keychain rapporte « not logged in » même quand l'hôte est authentifié.
• État Clerk du répertoire home : config sauvegardée, métadonnées en cache, et identifiants fallback vivent sous les répertoires config/data Clerk de l'utilisateur.
• Métadonnées du projet linked : résolues à partir du remote git du repo plus config Clerk. Les sandboxes avec état repo strippé ou lectures home-dir bloquées peuvent mal rapporter « not linked ».
• *Fichiers locaux `.env** : clés publishes et secret matérialisées parclerk env pull`.
• Accès réseau sortant vers Clerk : chaque appel Backend et Platform API.
• Navigateur + callback OAuth localhost : clerk auth login a besoin des deux.

En mode agent, le CLI fait maintenant un contrôle best-effort warn-once aux limites de la bibliothèque sensibles à l'hôte. Quand il détecte que l'état Clerk côté hôte ou les capacités système ne sont pas disponibles, 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.

Traitez cet avertissement comme faisant autorité. La commande peut continuer, mais tout échec auth, link, env, config, API, navigateur, ou callback OAuth de cette invocation est non fiable jusqu'à ce que vous relancez la même commande sur l'hôte.

Préférez 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é lancée accidentellement dans un sandbox et rapporte Not logged in, auth_required, not linked, env manquant, erreurs keychain/file permission, ou network failures, ne traitez pas le résultat comme faisant autorité. Relancez-la sur l'hôte avant d'agir dessus ou de la rapporter à l'utilisateur.

Invoquer le CLI

Avant de lancer une commande clerk, déterminez quel binaire invoquer et liez ce choix pour le reste de la session :

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

Si cela imprime latest ou toute version de confiance, utilisez bare clerk pour le reste de la session.

Sinon, revenez à un package runner, dans cet ordre (correspond à la logique preferredRunner du CLI lui-même, qui préfère le runner qui correspond au lockfile du projet) :

Yarn Classic (v1) n'a pas de dlx ; traitez ces projets comme « no preferred runner » et revenez au premier runner de la liste ci-dessus qui est sur PATH.

Le paquet npm publié est clerk, pas @clerk/cli. N'enseignez jamais npm install -g clerk comme chemin principal. Si le CLI global est périmé ou se comporte différemment de cette skill, mettez à jour l'installation globale ou revenez à la forme latest runner ci-dessus.

Prérequis (lancer au démarrage de la session pour les opérations non-setup)

Sauf si vous suivez clerk-setup, vérifiez que le CLI est authentifié, lié, et en bonne santé avant de lancer d'autres commandes Clerk dans une session :

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

Lancez toujours clerk doctor --json en premier. Cela attrape les échecs setup courants (not logged in, project not linked, missing keys, stale CLI version) d'avance, donc les commandes ultérieures ne échouent pas avec des erreurs confuses. En mode agent, cela inclut aussi une vérification Host execution qui avertit quand les répertoires Clerk côté hôte / credential ne sont pas inscriptibles, ce qui est le signal canonique que l'invocation courante est probablement sandboxée.

Chaque résultat a name, status (pass/warn/fail), message, optionnel detail, optionnel remedy (comment le corriger), et optionnel fix (label pour les problèmes auto-fixables). Analysez cela et agissez en conséquence, ou exposez-le à l'utilisateur. Si Host execution avertit, relancez la commande sur l'hôte avant de faire confiance à tout échec auth/link/env/API de la même exécution sandboxée. Relancez clerk doctor --json chaque fois qu'une commande ultérieure commence à mal se comporter.

Si clerk --version rapporte un CLI plus récent que ce que couvre cette skill, faites confiance à clerk <command> --help en priorité et rafraîchissez ce bundle skill à partir de sa source. L'inverse s'applique aussi : --accountless et les clés JSON accountless arrivent en CLI 3.3+ — sur un CLI plus ancien, utilisez l'alias --keyless ou faites une mise à jour.

Configuration accountless

clerk init ne requiert pas clerk auth login : sur un framework avec support accountless, un bootstrap non-authentifié sans --app, ou une exécution agent non-authentifiée sans --app ou lien projet existant, crée une app accountless non-revendiquée avec clés de développement temporaires — pas de compte, pas de navigateur, pas de drapeau. (Un humain signed-out qui le relance dans un projet existant obtient le flux login à la place — --accountless force le chemin clés-temporaires.) La plupart des commandes instance fonctionnent alors sur cette clé seule.

Deux choses à savoir avant de l'utiliser : le chemin accountless suit quelle que soit la clé sk_ locale — sk_live_ incluse, revendiquée ou non — donc passez --app <id> quand vous voulez une vrai app ; et clerk open retourne une URL de revendication équivalente aux identifiants, jamais sûre de coller dans un log ou PR.

Quelles commandes ont besoin d'un compte, et les règles complètes : auth.md.

Le modèle mental

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

Découvrez les endpoints — ne les mémorisez pas

Le CLI livre le catalogue OpenAPI de Clerk. Découvrez toujours les endpoints dynamiquement au lieu de deviner les chemins :

clerk api ls                  # lister chaque endpoint Backend API
clerk api ls users            # filtrer par mot-clé (correspond path, summary, tag, operationId)
clerk api ls --platform apps  # lister les endpoints Platform API

Utilisez ceci avant clerk api <path>. Si vous ne voyez pas l'endpoint attendu, il n'est probablement pas exposé.

La commande clerk api (la bête de somme)

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

# Requêtes GET
clerk api /users                                  # lister les users
clerk api /users/user_abc123                      # récupérer un
clerk api /users?limit=5&order_by=-created_at     # les paramètres de 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 de fichier ou stdin
clerk api /users --file payload.json
cat payload.json | clerk api /users

# Toujours prévisualiser les mutations d'abord
clerk api /users/user_abc123 -X DELETE --dry-run
clerk api /users/user_abc123 -X DELETE --yes      # passer confirmation une fois que vous avez vérifié

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

# Inclure les headers de réponse quand on débugge
clerk api /users --include

# Platform API (au niveau du compte, pas tenant data)
clerk api /v1/platform/applications --platform

# Frontend API (l'API publique client-facing de l'instance — ce que clerk-js appelle.
# Non-authentifiée ; --fapi et --platform ne peuvent pas être combinés, --secret-key est ignoré)
clerk api --fapi /environment

En mode humain, clerk api sans arguments ouvre un constructeur de requête interactif ; en mode agent, il imprime une guidance d'usage et exit 0 — toujours passer un endpoint (ou ls) explicitement à partir de scripts.

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

Toujours --dry-run une mutation avant de la lancer pour de vrai. Puis relancez 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. Le CLI valide et rejette les payloads malformé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.

Voir references/recipes.md pour les patterns concrets : lister/filtrer les users, créer des orgs, sessions d'impersonation, etc.

Inspecter les grands outputs (ne pas inonder votre contexte)

users list, apps list, config pull, et la plupart des GETs clerk api retournent des payloads qui peuvent faire plusieurs kilobytes ou megabytes. Les tenants production ont couramment des milliers de users ; une config instance peut être des centaines de champs de profondeur. Lire ces réponses dans la conversation coûte du context window pour aucun bénéfice. Sauvegardez la réponse dans un fichier d'abord, puis interrogez juste ce dont vous avez besoin avec jq :

# 1. Persister la réponse. Utilisez --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. Inspecter seulement ce dont vous avez besoin.
jq '.data | length'                       /tmp/users.json   # taille de la page courante
jq '.hasMore'                             /tmp/users.json   # y a-t-il plus de pages disponibles ?
jq '.data[0] | keys'                      /tmp/users.json   # découvrir la shape user une fois
jq '.data[] | {id, email_addresses}'      /tmp/users.json   # projeter vers quelques champs
jq '[.data[] | select(.banned)] | length' /tmp/users.json   # agréger sans lire les lignes

Si jq n'est pas disponible, revenez à Python ou Node - les deux peuvent streamer le fichier sans l'imprimer entièrement :

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 vous avez réellement besoin de voir la structure brute pour du debugging one-off. Quand vous parcourez les pages, écrivez chaque page dans son propre fichier (ex. page-${offset}.json) pour que les pages individuelles restent indépendamment inspectables.

Commandes core en un coup d'œil

clerk <command> --help est la source de vérité pour les drapeaux. Cette table est une indication, pas une spec. Avant de lancer une combinaison de commande ou drapeau non-familière, lancez clerk <command> --help une fois par session. Chaque commande définit aussi setExamples([...]) en source, que --help rend comme un bloc Examples copy-pasteable, donc vous avez rarement besoin de 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 sélecteurs (link sans --app, unlink sans --yes, users sans subcommand) soit auto-résolvent soit exit avec une erreur d'usage. clerk api sans args imprime une guidance d'usage et exit 0 ; passez un endpoint (ou ls) explicitement. Toujours passer les drapeaux explicites (--app, --yes) dans les appels scriptés.
• Les opérations sensibles à l'hôte émettent un avertissement sandbox une fois par invocation. L'état Clerk du répertoire home, l'accès keychain, les appels Clerk en réseau, le lancement du navigateur, et la configuration de callback OAuth localhost peuvent déclencher l'avertissement montré ci-dessus. S'il apparaît, relancez la même commande sur l'hôte avant de faire confiance au résultat.
• Si votre harness ne se présente pas clairement comme mode agent, forcez-le. Utilisez --mode agent ou CLERK_MODE=agent quand vous voulez que le comportement non-interactif du CLI et le chemin sandbox warning 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 va d'abord essayer un autolink basé clé silencieux ; s'il ne peut pas déterminer l'app sans ambiguïté, il exit et vous dit de passer --app.
• Pour init, suivez clerk-setup. Elle possède la support framework, accountless, app-linking, migration, et login-order guidance donc les instructions setup ont une source de vérité.
• --fresh est destructeur. Il remplace l'app temporaire et écrase les clés env et le breadcrumb .clerk/keyless.json sans prompt, orphelinant l'app précédente et ses users. Ne le passez jamais juste pour relancer init.
• unlink requiert --yes en mode agent. Il porte sur isAgent() && !options.yes et exit avec une erreur d'usage sans. Ceci est l'exception, pas le pattern - voir la balle suivante.
• Seul unlink requiert réellement --yes. Chaque autre porte de confirmation est écrite comme isHuman() && !options.yes, donc le mode agent la saute carrément : la mutation s'exécute sans prompt et sans erreur. Passer --yes est inoffensif mais ne change rien. Ne le traitez pas comme une porte de sécurité - --dry-run est la vrai.
• impersonate requiert le positional [user] en mode agent. Si un terme de recherche correspond à plusieurs users, il exit 2 listant les IDs user candidats — reessayez avec un ID user_... spécifique. La sortie est un objet JSON ({url, id, userId, actor, ...}); exposez url à l'utilisateur et capturez id — c'est la seule chance d'enregistrer la poignée revoke.
• webhooks listen est long-running. Lancez-le en background. En mode agent (ou avec --json) il émet NDJSON : une ligne ready ({type:"ready", relay_url, forward_to}), puis une ligne event par delivery — chaque ligne event peut être refeedée vers clerk webhooks verify --delivery.
• doctor --fix est ignoré. Analysez le champ remedy de la sortie doctor --json et agissez dessus vous-même.
• apps list et apps create défaut à JSON quand piped.
• users défaut à JSON quand piped, comme apps. clerk users list et clerk users create émettent JSON en mode agent. Bare clerk users (sans subcommand) est une erreur d'usage en mode agent - passez list, create, ou open explicitement. clerk users open requiert le positional user-id en mode agent et imprime un descripteur JSON au lieu de lancer un navigateur.
• deploy a un agent handoff plus une porte de vérification. En mode agent, bare clerk deploy est read-only et émet un handoff JSON. Il ne drive jamais l'assistant interactif. Ne dites pas à Claude ou un autre agent de lancer ! clerk deploy, parce que l'assistant a besoin de prompts stdin interactifs. Demandez à l'humain de lancer clerk deploy dans une nouvelle fenêtre terminal quand nécessaire, puis lancez clerk deploy status --mode agent pour vérifier l'accomplissement. Voir references/agent-mode.md.
• --input-json <json|@file|-> élargit JSON en drapeaux sur n'importe quelle commande (ex. clerk init --input-json '{"framework":"next","yes":true}'). Stdin a besoin du marqueur explicite - (echo '{"yes":true}' | clerk init --input-json -) ; le stdin piped nu n'est pas auto-détecté, donc les boucles shell et les commandes auto-reading (cat body.json | clerk api …) sont intactes. Placez --input-json après le leaf subcommand. 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 brut API, donc piped dans jq librement.
• Codes de sortie : 0 succès, 1 erreur runtime, 2 erreur usage/validation. doctor retourne 1 si un test a échoué.
• Format d'erreur : Les erreurs présentées à l'utilisateur impriment une ligne unique vers stderr et définissent un code de sortie non-zéro. Utilisez --verbose pour des stack traces quand vous debuguez.

Règles de sécurité pour usage autonome

1. Découvrir avant d'agir : clerk api ls <keyword> avant clerk api <path>.
2. Prévisualiser les mutations : --dry-run sur chaque config patch, config put, api -X POST/PATCH/PUT/DELETE.
3. Cibler explicitement en production : passez --instance prod au lieu de vous fier aux défauts, et confirmez avec l'utilisateur avant toute mutation production.
4. Ne jamais commiter des secrets : env pull écrit vers .env.local (qui devrait être gitignored). Ne collez pas les clés secret dans le code ou le chat.
5. Utilisez doctor --json pour diagnostiquer avant d'assumer que le CLI est cassé.

Références

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