CLI de Clerk
El binario clerk es una puerta de enlace preautenticada a las API de Backend y Plataforma de Clerk, además de herramientas a nivel de proyecto (autenticación, enlace, obtención de variables de entorno, configuración de instancias). Cuando el usuario solicite algo que involucre un recurso de Clerk, usa clerk primero en lugar de implementar curl manualmente.
Esta habilidad está dirigida a
clerk latest. Siclerk --versionno coincide con la versión más reciente de la CLI, actualízala conclerk skill installo un ejecutor de paquetes comobunx clerk@latest. El binario es siempre la fuente de verdad, por lo que debes ejecutarclerk <comando> --helppara verificar cualquier afirmación de esta habilidad.
Entorno de ejecución (prefiere el host, comprende la advertencia de sandbox)
La mayoría de los agentes de IA para codificación ejecutan comandos de shell en un sandbox donde el directorio home del usuario, el llavero de claves del sistema, el lanzamiento del navegador, el enlace de callback a localhost o el acceso a la red pueden estar bloqueados. La CLI de Clerk depende de todas estas capacidades del host:
- Almacén de credenciales del SO:
clerk auth loginalmacena el token OAuth en el llavero del sistema. Un sandbox sin acceso al llavero reportará "no has iniciado sesión" incluso si el host está autenticado. - Estado de Clerk en el directorio home: la configuración guardada, los metadatos en caché y las credenciales de respaldo residen bajo los directorios de configuración/datos de Clerk del usuario.
- Metadatos del proyecto vinculado: resueltos a partir del remoto git del repositorio más la configuración de Clerk. Los sandbox con estado del repositorio reducido o acceso al directorio home bloqueado pueden informar incorrectamente "no vinculado".
- Archivos
.env*locales: claves publicables y secretas materializadas porclerk env pull. - Acceso de red saliente a Clerk: cada llamada a las API de Backend y Plataforma.
- Callback OAuth de navegador + localhost:
clerk auth loginnecesita ambos.
En modo agente, la CLI ahora realiza una verificación única de advertencia (best-effort) en los límites de las bibliotecas sensibles al host. Cuando detecta que el estado de Clerk exclusivo del host o las capacidades del sistema no están disponibles, emite:
El estado de Clerk exclusivo del host o las capacidades del sistema pueden no estar disponibles en modo agente. Esto puede ser una ejecución en sandbox.
Vuelve a ejecutar este comando en el shell del host antes de confiar en fallos de autenticación, enlace, entorno o API.
Trata esa advertencia como autorizada. El comando puede continuar, pero cualquier fallo de autenticación, enlace, entorno, configuración, API, navegador o callback OAuth de esa invocación no es confiable hasta que vuelvas a ejecutar el mismo comando en el host.
Prefiere estos comandos en el shell del usuario, no en un sandbox:
clerk doctor, clerk whoami, clerk auth login, clerk link, clerk env pull,
clerk apps ..., clerk config ..., clerk api ....
Si un comando se ejecutó accidentalmente en un sandbox y reporta No has iniciado sesión,
auth_required, no vinculado, variables de entorno faltantes, errores de permisos de llavero/archivo o fallos de red, no trates el resultado como autorizado. Vuelve a ejecutarlo en el host antes de actuar en base a él o informarlo al usuario.
Invocación de la CLI
Antes de ejecutar cualquier comando clerk, determina qué binario invocar y vincula esa elección para el resto de la sesión:
# 1. Prefiere un binario instalado globalmente cuando coincida con la versión objetivo de la habilidad.
command -v clerk >/dev/null 2>&1 && clerk --version
Si eso imprime latest o cualquier versión que consideres confiable, usa clerk simple para el resto de la sesión.
De lo contrario, recurre a un ejecutor de paquetes, en este orden (coincide con la lógica preferredRunner de la propia CLI, que prefiere el ejecutor que coincida con el archivo de bloqueo del proyecto):
| Gestor de paquetes del proyecto | Invocación |
|---|---|
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) no tiene dlx; trata esos proyectos como "sin ejecutor preferido" y recurre al primer ejecutor de la lista anterior que esté en PATH.
El paquete npm publicado es clerk, no @clerk/cli. Nunca enseñes npm install -g clerk como ruta principal. Si la CLI global está desactualizada o se comporta de manera diferente a esta habilidad, actualiza la instalación global o recurre a la forma de ejecutor latest anterior.
Requisitos previos (ejecutar al inicio de la sesión)
Antes de ejecutar cualquier otro comando de Clerk en una sesión, verifica que la CLI esté autenticada, vinculada y saludable:
clerk --version # confirma que el binario está en PATH
clerk doctor --json # verificación de salud estructurada; sale con 1 si algo falló
Ejecuta siempre clerk doctor --json primero. Detecta los fallos de configuración comunes (no has iniciado sesión, proyecto no vinculado, claves faltantes, versión de CLI desactualizada) de antemano, para que los comandos posteriores no fallen con errores confusos. En modo agente, también incluye una verificación de Ejecución del host que advierte cuando los directorios de configuración/credenciales del lado del host de Clerk no son escribibles, que es la señal canónica de que la invocación actual probablemente está en un sandbox.
Cada resultado tiene name, status (pass/warn/fail), message, detail opcional, remedy opcional (cómo solucionarlo) y fix opcional (etiqueta para problemas solucionables automáticamente). Analízalo y actúa en consecuencia, o preséntalo al usuario. Si Ejecución del host advierte, vuelve a ejecutar el comando en el host antes de confiar en cualquier fallo de autenticación/enlace/entorno/API de la misma ejecución en sandbox. Vuelve a ejecutar clerk doctor --json cada vez que un comando posterior comience a comportarse mal.
Si clerk --version reporta una CLI más nueva que la que cubre esta habilidad, confía primero en clerk <comando> --help y actualiza este paquete de habilidades desde su fuente.
El modelo mental
| Capa | Qué hace | Comandos |
|---|---|---|
| Sesión / proyecto | Autenticación, vincular un repositorio a una aplicación de Clerk, obtener claves de entorno | auth login, link, unlink, whoami, env pull, doctor |
| Configuración de instancia | Gestiona la configuración (proveedores sociales, duración de sesiones, etc.) para una instancia específica | config pull, config schema, config patch, config put |
| API de Backend (predeterminada) | Datos en tiempo de ejecución: usuarios, organizaciones, sesiones, invitaciones, plantillas JWT, webhooks | clerk api <ruta> |
API de Plataforma (--platform) | A nivel de cuenta: aplicaciones, instancias, facturación | clerk api --platform <ruta> |
Un proyecto está "vinculado" a una aplicación a través de clerk link. Una vez vinculado, la mayoría de los comandos resuelven automáticamente la aplicación objetivo y la instancia de desarrollo desde el remoto git del repositorio. Para apuntar a otra cosa, pasa --app <id> y/o --instance dev|prod|<instance_id>. Consulta references/auth.md para conocer el orden de resolución completo.
Descubre los endpoints - no los memorices
La CLI incluye el catálogo OpenAPI de Clerk. Siempre descubre los endpoints dinámicamente en lugar de adivinar las rutas:
clerk api ls # listar cada endpoint de la API de Backend
clerk api ls users # filtrar por palabra clave (coincide con ruta, resumen, etiqueta, operationId)
clerk api ls --platform apps # listar endpoints de la API de Plataforma
Usa esto antes de clerk api <ruta>. Si no ves el endpoint que esperabas, probablemente no esté expuesto.
El comando clerk api (el caballo de batalla)
clerk api realiza llamadas HTTP autenticadas. Resuelve claves automáticamente, detecta el método a partir de la presencia del cuerpo, admite stdin y puede previsualizar mutaciones con --dry-run.
# Solicitudes GET
clerk api /users # listar usuarios
clerk api /users/user_abc123 # obtener uno
clerk api /users?limit=5&order_by=-created_at # los parámetros de consulta funcionan en línea
# Solicitudes de mutación
clerk api /users -d '{"email_address":["[email protected]"]}' # POST (detectado automáticamente desde el cuerpo)
clerk api /users/user_abc123 -X PATCH -d '{"first_name":"A"}'
clerk api /users/user_abc123 -X DELETE
# Cuerpo desde archivo o stdin
clerk api /users --file payload.json
cat payload.json | clerk api /users
# Siempre previsualiza las mutaciones primero
clerk api /users/user_abc123 -X DELETE --dry-run
clerk api /users/user_abc123 -X DELETE --yes # omitir confirmación una vez que hayas verificado
# Apuntar a una aplicación/instancia específica
clerk api /users --app app_abc123 --instance prod
# Incluir encabezados de respuesta al depurar
clerk api /users --include
# API de Plataforma (a nivel de cuenta, no datos de tenant)
clerk api /v1/platform/applications --platform
Para la configuración de instancias, prefiere los comandos dedicados clerk config ... sobre las rutas sin procesar de la API de Plataforma /config. Manejan la previsualización, la comparación y la confirmación de manera más limpia que la forma de endpoint sin procesar.
Siempre usa --dry-run en una mutación antes de ejecutarla realmente. Luego vuelve a ejecutarla sin --dry-run (agrega --yes si estás seguro). En modo agente, la confirmación interactiva se omite, por lo que --dry-run es la única red de seguridad para llamadas destructivas.
Los cuerpos JSON deben ser JSON válidos. La CLI valida y rechaza cargas útiles mal formadas.
Las rutas de los endpoints se pueden proporcionar con o sin el prefijo /v1/ - ambos funcionan para las llamadas a la API de Backend. La CLI normaliza.
Consulta references/recipes.md para patrones concretos: listar/filtrar usuarios, crear organizaciones, sesiones de impersonación, etc.
Inspeccionar salidas grandes (no saturen tu contexto)
users list, apps list, config pull y la mayoría de los GET de clerk api devuelven cargas útiles que pueden tener muchos kilobytes o megabytes. Los tenants de producción comúnmente tienen miles de usuarios; una configuración de instancia puede tener cientos de campos de profundidad. Leer esas respuestas en la conversación consume espacio de la ventana de contexto sin beneficio. Guarda la respuesta en un archivo primero, luego consulta solo lo que necesitas con jq:
# 1. Persistir la respuesta. Usa --limit 250 para maximizar el tamaño de página para la lista de usuarios.
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. Inspecciona solo lo que necesitas.
jq '.data | length' /tmp/users.json # tamaño de página actual
jq '.hasMore' /tmp/users.json # ¿hay más páginas disponibles?
jq '.data[0] | keys' /tmp/users.json # descubre la forma del usuario una vez
jq '.data[] | {id, email_addresses}' /tmp/users.json # proyectar a unos pocos campos
jq '[.data[] | select(.banned)] | length' /tmp/users.json # agregar sin leer filas completas
Si jq no está disponible, recurre a Python o Node; ambos pueden transmitir el archivo sin imprimirlo por completo:
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)'
Usa cat / head en el archivo solo cuando realmente necesites ver la estructura sin procesar para una depuración puntual. Al recorrer páginas, escribe cada página en su propio archivo (por ejemplo, page-${offset}.json) para que las páginas individuales permanezcan independientemente inspeccionables.
Comandos principales de un vistazo
| Comando | Propósito | Banderas clave |
|---|---|---|
clerk init | Andamiar Clerk en un proyecto. --starter solo admite bootstrap para Next.js, React Router, Astro, Nuxt, TanStack Start, React, Vue y JavaScript. | --framework, --pm, --name (con --starter), --app, --starter, -y, --no-skills |
clerk auth login | Inicio de sesión OAuth en navegador (almacena token). Modo agente: no-op si ya has iniciado sesión. Sin sesión almacenada, aún abre un navegador y vincula un callback de localhost, por lo que no es desatendido; prefiere CLERK_PLATFORM_API_KEY para flujos headless. Alias: signup, signin, sign-in. Acceso directo de nivel superior: clerk login. | - |
clerk auth logout | Limpiar credenciales almacenadas. Alias: signout, sign-out. Acceso directo de nivel superior: clerk logout. | - |
clerk whoami | Imprimir el correo electrónico que ha iniciado sesión. |
…[truncado para traducción]