CLI do Clerk
O binário clerk é um gateway pré-autenticado para a API Backend e a API Platform do Clerk, além de ferramentas de nível de projeto (autenticação, vinculação, extração de env, configuração de instância). Quando o usuário perguntar sobre algo que toque em um recurso do Clerk, use o clerk primeiro em vez de criar manualmente um curl.
Esta skill tem como alvo o clerk
latest. Seclerk --versiondiscordar da versão mais recente disponível da CLI, atualize-a comclerk skill installou um executor de pacotes comobunx clerk@latest. O binário é sempre a fonte da verdade, portanto, executeclerk <comando> --helppara verificar qualquer coisa que esta skill afirmar.
Ambiente de execução (prefira o host, entenda o aviso de sandbox)
A maioria dos agentes de codificação de IA executam comandos de shell em uma sandbox onde o diretório home do usuário, o chaveiro do SO, a abertura do navegador, o callback localhost ou o acesso à rede podem estar bloqueados. A CLI do Clerk depende de todas essas capacidades do host:
- Armazenamento de credenciais do SO:
clerk auth loginarmazena o token OAuth no chaveiro do sistema. Uma sandbox sem acesso ao chaveiro relata "não logado" mesmo quando o host está autenticado. - Estado do Clerk no diretório home: configuração salva, metadados em cache e credenciais de fallback residem nos diretórios de configuração/dados do Clerk do usuário.
- Metadados de projeto vinculado: resolvidos a partir do repositório git remoto mais a configuração do Clerk. Sandboxes com estado de repositório removido ou leituras de diretório home bloqueadas podem relatar incorretamente "não vinculado".
- Arquivos
.env*locais: chaves publicáveis e secretas materializadas porclerk env pull. - Acesso de rede de saída para o Clerk: toda chamada às APIs Backend e Platform.
- Navegador + callback OAuth localhost:
clerk auth loginprecisa de ambos.
No modo agente, a CLI agora faz uma verificação de aviso único de melhor esforço nos limites das bibliotecas sensíveis ao host. Quando detecta que o estado do Clerk apenas no host ou as capacidades do sistema estão indisponíveis, ela emite:
Estado do Clerk apenas no host ou capacidades do sistema podem estar indisponíveis no modo agente. Pode ser uma execução em sandbox.
Execute este comando novamente no shell do host antes de confiar em falhas de auth, link, env ou API.
Trate esse aviso como autoritativo. O comando pode continuar, mas qualquer falha de auth, link, env, config, API, navegador ou callback OAuth dessa invocação não é confiável até que você execute o mesmo comando novamente no host.
Prefira estes comandos no shell do host do usuário, não em uma sandbox:
clerk doctor, clerk whoami, clerk auth login, clerk link, clerk env pull, clerk apps ..., clerk config ..., clerk api ....
Se um comando foi executado acidentalmente em uma sandbox e ele relatar Not logged in, auth_required, not linked, env ausente, erros de permissão de chaveiro/arquivo ou falhas de rede, não trate o resultado como autoritativo. Execute-o novamente no host antes de agir sobre ele ou relatá-lo ao usuário.
Invocando a CLI
Antes de executar qualquer comando clerk, descubra qual binário invocar e fixe essa escolha para o resto da sessão:
# 1. Prefira um binário instalado globalmente quando corresponder à versão alvo da skill.
command -v clerk >/dev/null 2>&1 && clerk --version
Se isso imprimir latest ou qualquer versão que você confie, use apenas clerk para o resto da sessão.
Caso contrário, recorra a um executor de pacotes, nesta ordem (corresponde à lógica preferredRunner da própria CLI, que prefere o runner que corresponde ao arquivo de bloqueio do projeto):
| Gerenciador de pacotes do projeto | Invocação |
|---|---|
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ão tem dlx; trate esses projetos como "sem runner preferido" e recorra ao primeiro runner da lista acima que estiver no PATH.
O pacote npm publicado é clerk, não @clerk/cli. Nunca ensine npm install -g clerk como o caminho principal. Se a CLI global estiver desatualizada ou se comportar de forma diferente desta skill, atualize a instalação global ou recorra à forma de runner latest acima.
Pré-requisitos (execute no início da sessão)
Antes de executar qualquer outro comando do Clerk em uma sessão, verifique se a CLI está autenticada, vinculada e saudável:
clerk --version # confirme que o binário está no PATH
clerk doctor --json # verificação de saúde estruturada; saia com 1 se algo falhar
Sempre execute clerk doctor --json primeiro. Ele detecta as falhas comuns de configuração (não logado, projeto não vinculado, chaves ausentes, versão da CLI desatualizada) antecipadamente, para que comandos posteriores não falhem com erros confusos. No modo agente, ele também inclui uma verificação de Host execution que avisa quando os diretórios de configuração/credenciais do lado do host do Clerk não são graváveis, que é o sinal canônico de que a invocação atual provavelmente está em sandbox.
Cada resultado tem nome, status (pass/warn/fail), mensagem, detalhe opcional, remedio opcional (como corrigi-lo) e correcao opcional (rótulo para problemas corrigíveis automaticamente). Analise isso e aja de acordo, ou mostre ao usuário. Se Host execution avisar, execute o comando novamente no host antes de confiar em qualquer falha de auth/link/env/API da mesma execução em sandbox. Execute clerk doctor --json novamente sempre que um comando posterior começar a se comportar mal.
Se clerk --version relatar uma CLI mais nova do que esta skill cobre, confie primeiro em clerk <comando> --help e atualize este pacote de skill de sua fonte.
O modelo mental
| Camada | O que faz | Comandos |
|---|---|---|
| Sessão / projeto | Autenticação, vincular um repositório a um aplicativo Clerk, puxar chaves de env | auth login, link, unlink, whoami, env pull, doctor |
| Configuração de instância | Gerenciar a configuração (provedores sociais, durações de sessão, etc.) para uma instância específica | config pull, config schema, config patch, config put |
| API Backend (padrão) | Dados de tempo de execução: usuários, organizações, sessões, convites, modelos JWT, webhooks | clerk api <caminho> |
API Platform (--platform) | Nível de conta: aplicações, instâncias, faturamento | clerk api --platform <caminho> |
Um projeto é "vinculado" a uma aplicação via clerk link. Uma vez vinculado, a maioria dos comandos resolve automaticamente o aplicativo alvo e a instância de desenvolvimento a partir do repositório git remoto. Para direcionar outra coisa, passe --app <id> e/ou --instance dev|prod|<id_instancia>. Veja references/auth.md para a ordem de resolução completa.
Descubra endpoints - não os memorize
A CLI vem com o catálogo OpenAPI do Clerk. Sempre descubra endpoints dinamicamente em vez de adivinhar caminhos:
clerk api ls # liste todos os endpoints da API Backend
clerk api ls users # filtre por palavra-chave (corresponde a caminho, resumo, tag, operationId)
clerk api ls --platform apps # liste endpoints da API Platform
Use isso antes de clerk api <caminho>. Se você não vir o endpoint esperado, provavelmente ele não está exposto.
O comando clerk api (o cavalo de batalha)
clerk api faz chamadas HTTP autenticadas. Ele resolve chaves automaticamente, detecta método automaticamente a partir da presença do corpo, suporta entrada padrão e pode visualizar mutações com --dry-run.
# Requisições GET
clerk api /users # liste usuários
clerk api /users/user_abc123 # busque um
clerk api /users?limit=5&order_by=-created_at # parâmetros de consulta funcionam inline
# Requisições de mutação
clerk api /users -d '{"email_address":["[email protected]"]}' # POST (detectado automaticamente a partir do corpo)
clerk api /users/user_abc123 -X PATCH -d '{"first_name":"A"}'
clerk api /users/user_abc123 -X DELETE
# Corpo de arquivo ou entrada padrão
clerk api /users --file payload.json
cat payload.json | clerk api /users
# Sempre visualize mutações primeiro
clerk api /users/user_abc123 -X DELETE --dry-run
clerk api /users/user_abc123 -X DELETE --yes # pule a confirmação depois de verificar
# Direcione um aplicativo/instância específico
clerk api /users --app app_abc123 --instance prod
# Inclua cabeçalhos de resposta ao depurar
clerk api /users --include
# API Platform (nível de conta, não dados do locatário)
clerk api /v1/platform/applications --platform
Para configuração de instância, prefira os comandos dedicados clerk config ... em vez de caminhos /config brutos da API Platform. Eles lidam com dry-run, diff e confirmação de forma mais limpa do que a forma de endpoint bruto.
Sempre use --dry-run em uma mutação antes de executá-la de verdade. Em seguida, execute novamente sem --dry-run (adicione --yes se tiver certeza). No modo agente, a confirmação interativa é ignorada, então --dry-run é a única rede de segurança para chamadas destrutivas.
Os corpos JSON devem ser JSON válido. A CLI valida e rejeita payloads malformados.
Os caminhos dos endpoint podem ser fornecidos com ou sem o prefixo /v1/ - ambos funcionam para chamadas à API Backend. A CLI normaliza.
Veja references/recipes.md para padrões concretos: listar/filtrar usuários, criar organizações, sessões de impersonação, etc.
Inspecionando grandes saídas (não inunde seu contexto)
users list, apps list, config pull e a maioria dos clerk api GET retornam payloads que podem ter muitos kilobytes ou megabytes. Locatários de produção comumente têm milhares de usuários; uma configuração de instância pode ter centenas de campos. Ler essas respostas na conversa custa janela de contexto sem benefício. Salve a resposta em um arquivo primeiro, depois consulte apenas o que você precisa com jq:
# 1. Persista a resposta. Use --limit 250 para maximizar o tamanho da página para listas de usuários.
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. Inspecione apenas o que você precisa.
jq '.data | length' /tmp/users.json # tamanho da página atual
jq '.hasMore' /tmp/users.json # mais páginas disponíveis?
jq '.data[0] | keys' /tmp/users.json # descubra a forma do usuário uma vez
jq '.data[] | {id, email_addresses}' /tmp/users.json # projete para alguns campos
jq '[.data[] | select(.banned)] | length' /tmp/users.json # agregue sem ler linhas
Se jq não estiver disponível, recorra ao Python ou Node - ambos podem transmitir o arquivo sem imprimi-lo inteiro:
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)'
Use cat / head no arquivo apenas quando você realmente precisar ver a estrutura bruta para depuração pontual. Ao percorrer páginas, escreva cada página em seu próprio arquivo (por exemplo, page-${offset}.json) para que páginas individuais permaneçam inspecionáveis independentemente.
Comandos principais de relance
| Comando | Propósito | Flags principais |
|---|---|---|
clerk init | Estruturar Clerk em um projeto. --starter suporta apenas bootstraps para Next.js, React Router, Astro, Nuxt, TanStack Start, React, Vue, e JavaScript. | --framework, --pm, --name (com --starter), --app, --starter, -y, --no-skills |
clerk auth login | Login via navegador OAuth (armazena token). Modo agente: não faz nada se já logado. Sem sessão armazenada ainda abre um navegador e vincula um callback localhost, portanto não é automatizado; prefira CLERK_PLATFORM_API_KEY para fluxos sem cabeça. Aliases: signup, signin, sign-in. Atalho de nível superior: clerk login. | - |
clerk auth logout | Limpa credenciais armazenadas. Aliases: signout, sign-out. Atalho de nível superior: clerk logout. | - |
clerk whoami | Imprime o email logado. |