diff --git a/.agents/skills/clerk-backend-api/SKILL.md b/.agents/skills/clerk-backend-api/SKILL.md new file mode 100644 index 0000000..5a3bbfc --- /dev/null +++ b/.agents/skills/clerk-backend-api/SKILL.md @@ -0,0 +1,426 @@ +--- +name: clerk-backend-api +description: "Clerk Backend REST API explorer and executor. Browse tags, inspect endpoint schemas, and execute authenticated requests. Use when listing users, managing organizations, or calling any Clerk API endpoint." +allowed-tools: Bash, Read, Grep, Skill, WebFetch +license: MIT +compatibility: Requires CLERK_SECRET_KEY (sk_*) for Backend API calls. +--- + +## Options context + +User Prompt: $ARGUMENTS + +## CRITICAL: Mandatory checks before EVERY write request + +Before ANY POST / PATCH / PUT / DELETE, you MUST do ALL of the following in your response: + +1. **Check CLERK_SECRET_KEY** — verify it is set: + ```bash + echo $CLERK_SECRET_KEY | head -c 10 + ``` + If empty, stop and ask the user. Do not proceed without a valid key. + +2. **Check CLERK_BAPI_SCOPES** — run: + ```bash + echo $CLERK_BAPI_SCOPES + ``` + Inspect the output. If scopes are missing or do not include the required write permission, tell the user: *"This is a write operation and your current scopes may not allow it. Rerun with --admin to bypass?"* Do NOT attempt the request and fail — ask first. + +3. **For DELETE requests:** warn explicitly that the action is **IRREVERSIBLE** and list exactly what data will be permanently destroyed (user record, all sessions, all memberships, all associated data). Require explicit confirmation before proceeding. This warning is MANDATORY — never skip it. + +4. **For metadata operations:** always explain which metadata type is being used and why (see Metadata types section below). + +--- + +## FAST PATH: Common operations (use directly, no spec fetching needed) + +For the operations below, skip spec fetching and execute immediately using these exact templates. Substitute `$CLERK_SECRET_KEY`, `$USER_ID`, `$ORG_ID`, `$EMAIL` as needed from the user's context. + +### Create organization + invite member (two-step) + +```bash +# Step 1 — Create organization +ORG=$(curl -s -X POST "https://api.clerk.com/v1/organizations" \ + -H "Authorization: Bearer $CLERK_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d "{\"name\": \"Acme Corp\", \"created_by\": \"$USER_ID\"}") +echo "$ORG" | python3 -c "import sys,json; d=json.load(sys.stdin); print(json.dumps(d, indent=2))" + +# Step 2 — Extract org ID +ORG_ID=$(echo "$ORG" | python3 -c "import sys,json; print(json.load(sys.stdin)['id'])") + +# Step 3 — Invite member with role +curl -s -X POST "https://api.clerk.com/v1/organizations/${ORG_ID}/invitations" \ + -H "Authorization: Bearer $CLERK_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d "{\"email_address\": \"user@example.com\", \"role\": \"org:admin\"}" \ + | python3 -c "import sys,json; print(json.dumps(json.load(sys.stdin), indent=2))" +``` + +**Roles:** use `"org:admin"` or `"org:member"` (always prefix with `org:`). + +### SDK equivalent (for Next.js / TypeScript projects with `@clerk/nextjs` or `@clerk/backend`) + +```typescript +import { clerkClient } from '@clerk/nextjs/server' +// OR if using @clerk/backend directly: +// import { createClerkClient } from '@clerk/backend' +// const clerkClient = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY }) + +// Step 1: Create organization +const org = await clerkClient.organizations.createOrganization({ + name: 'Acme Corp', + createdBy: userId, // required — the ID of the user creating the org +}) + +// Step 2: Invite member to the org +const invitation = await clerkClient.organizations.createOrganizationInvitation({ + organizationId: org.id, + emailAddress: 'user@example.com', + role: 'org:admin', // or 'org:member' +}) +``` + +### Update user metadata + +**Always explain the three metadata types before asking which to use:** + +| Type | Field | Readable by | Writable by | Use for | +|------|-------|-------------|-------------|---------| +| Public | `public_metadata` | Client + Server | **Server only** | Plan tier, roles, feature flags the frontend reads | +| Private | `private_metadata` | **Server only** | **Server only** | Stripe IDs, compliance flags, internal identifiers | +| Unsafe | `unsafe_metadata` | Client + Server | Client + Server | Ephemeral UI state, onboarding steps (client-writable — avoid sensitive data) | + +**For `plan: 'pro'` and `onboarded: true` — use `public_metadata`** (frontend-readable, server-writable): + +```bash +curl -s -X PATCH "https://api.clerk.com/v1/users/${USER_ID}" \ + -H "Authorization: Bearer $CLERK_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '{"public_metadata": {"plan": "pro", "onboarded": true}}' \ + | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Updated user {d[\"id\"]}: public_metadata={d.get(\"public_metadata\")}')" +``` + +**SDK equivalent:** + +```typescript +import { clerkClient } from '@clerk/nextjs/server' +// OR: import { createClerkClient } from '@clerk/backend' + +await clerkClient.users.updateUser(userId, { + publicMetadata: { plan: 'pro', onboarded: true }, // readable by client, writable server-only + // privateMetadata: { stripeId: 'cus_xxx' }, // server-only read AND write + // unsafeMetadata: { step: 'welcome' }, // client-writable, avoid sensitive data +}) +``` + +**Note:** REST API uses `snake_case` (`public_metadata`). SDK uses `camelCase` (`publicMetadata`). + +### List users (last 7 days) + +```bash +curl -s "https://api.clerk.com/v1/users?limit=100&offset=0&order_by=-created_at&created_at=gt:$(date -d '7 days ago' +%s 2>/dev/null || date -v-7d +%s)000" \ + -H "Authorization: Bearer $CLERK_SECRET_KEY" \ + | python3 -c " +import sys, json +data = json.load(sys.stdin) +if isinstance(data, list): + print(f'Found {len(data)} users:') + for u in data: + print(f' {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"no email\")}') +else: + print(json.dumps(data, indent=2)) +" +``` + +### Delete user (confirm required) + +```bash +# ONLY run after explicit user confirmation +curl -s -X DELETE "https://api.clerk.com/v1/users/${USER_ID}" \ + -H "Authorization: Bearer $CLERK_SECRET_KEY" \ + | python3 -c "import sys,json; d=json.load(sys.stdin); print(f'Deleted: {d}')" +``` + +--- + +## Clerk Backend API — Full Endpoint Reference + +Base URL: `https://api.clerk.com/v1` +Auth: `Authorization: Bearer $CLERK_SECRET_KEY` on every request. + +### Users + +**List users** +``` +GET /v1/users +Query params: limit (max 500, default 10), offset, order_by (+/-created_at, +/-updated_at, +/-email_address, +/-web3wallet, +/-first_name, +/-last_name, +/-phone_number, +/-username, +/-last_active_at, +/-last_sign_in_at), email_address[], phone_number[], username[], web3wallet[], user_id[], query, created_at (ISO 8601 range: gt:TIMESTAMP or lt:TIMESTAMP in Unix ms) +Returns: array of User objects +``` + +**Get user** +``` +GET /v1/users/{user_id} +Returns: User object +``` + +**Update user** +``` +PATCH /v1/users/{user_id} +Body (JSON, snake_case): { public_metadata, private_metadata, unsafe_metadata, first_name, last_name, username, ... } +``` + +**Delete user — IRREVERSIBLE** +``` +DELETE /v1/users/{user_id} +Destroys: user record, all sessions, all memberships, all associated data +Returns: { id, object, deleted: true } +``` +Always warn the user this is permanent and confirm before proceeding. + +### Organizations + +**Create organization** +``` +POST /v1/organizations +Body: { name: string, created_by: string (user_id), public_metadata?, private_metadata?, max_allowed_memberships? } +Returns: Organization object with { id, name, slug, ... } +``` + +**List organizations** +``` +GET /v1/organizations +Query params: limit, offset, query, order_by +``` + +**Invite member** +``` +POST /v1/organizations/{organization_id}/invitations +Body: { email_address: string, role: string ("org:admin" or "org:member"), public_metadata?, private_metadata? } +Returns: OrganizationInvitation object +``` + +--- + +## How to execute requests + +**ALWAYS execute requests with direct `curl` commands.** Use the spec-extraction scripts (`api-specs-context.sh`, `extract-tags.js`, `extract-endpoint-detail.sh`) to discover endpoints, but make actual API calls with `curl`. Do NOT use `scripts/execute-request.sh` — it's a local dev helper, not for agent use. + +Template for GET requests: +```bash +curl -s "https://api.clerk.com/v1${PATH}${QUERY_STRING}" \ + -H "Authorization: Bearer $CLERK_SECRET_KEY" +``` + +Template for POST/PATCH requests: +```bash +curl -s -X ${METHOD} "https://api.clerk.com/v1${PATH}" \ + -H "Authorization: Bearer $CLERK_SECRET_KEY" \ + -H "Content-Type: application/json" \ + -d '${BODY_JSON}' +``` + +Template for DELETE requests: +```bash +curl -s -X DELETE "https://api.clerk.com/v1${PATH}" \ + -H "Authorization: Bearer $CLERK_SECRET_KEY" +``` + +**After getting the response:** Parse and display it clearly. Use `python3 -c "import sys,json; data=json.load(sys.stdin); print(json.dumps(data, indent=2))"` to pretty-print JSON. Extract key fields (id, email, name, etc.) and summarize them for the user. + +--- + +## API specs context + +Before doing anything outside the FAST PATH, fetch the available spec versions and tags by running: +```bash +bash scripts/api-specs-context.sh +``` + +Use the output to determine the latest version and available tags. + +**Caching:** If you already fetched the spec context earlier in this conversation, do NOT fetch it again. Reuse the version and tags from the previous call. + +--- + +## Rules + +- For common operations (list users, create org, invite, update metadata, delete user): use the FAST PATH above — do NOT fetch specs first. +- Always disregard endpoints/schemas related to `platform`. +- Always confirm before performing write requests (POST/PUT/PATCH/DELETE). +- For DELETE operations, always warn the user that the action is **irreversible** and mention what data will be lost (user record, sessions, memberships). This warning is MANDATORY — never skip it. +- For write operations (POST/PUT/PATCH/DELETE), check `CLERK_BAPI_SCOPES` before attempting the request. If missing or insufficient, ask the user upfront. Do NOT attempt and fail — ask before executing. This check is MANDATORY. +- For metadata operations, always explain all three types (public, private, unsafe) and recommend the appropriate one. +- Pagination: always use `limit` + `offset` and mention that results may be paginated for large datasets. +- Use direct curl commands for all API calls — never use `scripts/execute-request.sh`. + +--- + +## Rate Limits & Gotchas + +### Rate Limits + +| Environment | Limit | +|-------------|-------| +| Production | 1,000 requests / 10 seconds | +| Development | 100 requests / 10 seconds | +| Single invitations | 100 / hour | +| Bulk invitations | 25 / hour | +| Org invitations | 250 / hour | +| Frontend API sign-in creation | 5 / 10 seconds | +| Frontend API sign-in attempts | 3 / 10 seconds | +| List users max per page | 500 | + +`currentUser()` makes a real API call that counts against rate limits. Use `auth()` for just the session claims — it reads from the token without an API call. + +### Metadata Overwrites (Not Merges) + +`updateUser({ publicMetadata: { role: 'admin' } })` REPLACES all public metadata, not merges. To add a field without losing existing data: read first, spread, then write. + +Wrong: +```typescript +await clerkClient.users.updateUser(userId, { publicMetadata: { newField: 'value' } }) +``` +This DELETES all other `publicMetadata` fields. + +Right: +```typescript +const user = await clerkClient.users.getUser(userId) +await clerkClient.users.updateUser(userId, { + publicMetadata: { ...user.publicMetadata, newField: 'value' }, +}) +``` + +--- + +## Modes + +Determine the active mode based on the user prompt in [Options context](#options-context): + +| Mode | Trigger | Behavior | +|------|---------|----------| +| `help` | Prompt is empty, or contains only `help` / `-h` / `--help` | Print usage examples (step 0) | +| `browse` | Prompt is `tags`, or a tag name (e.g. `Users`) | List all tags or endpoints for a tag | +| `execute` | Specific endpoint (e.g. `GET /users`) or natural language action (e.g. "get user john_doe") | Look up endpoint, execute request | +| `detail` | Endpoint + `help` / `-h` / `--help` (e.g. `GET /users help`) | Show endpoint schema, don't execute | + +--- + +## Your Task + +Use the **LATEST VERSION** from [API specs context](#api-specs-context) by default. If the user specifies a different version (e.g. `--version 2024-10-01`), use that version instead. + +Determine the active mode, then follow the applicable steps below. + +--- + +### 0. Print usage + +**Modes:** `help` only — **Skip** for `browse`, `execute`, and `detail`. + +Print the following examples to the user verbatim: + +``` +Browse + /clerk-backend-api tags — list all tags + /clerk-backend-api Users — browse endpoints for the Users tag + /clerk-backend-api Users version 2025-11-10.yml — browse using a different version + +Execute + /clerk-backend-api GET /users — fetch all users + /clerk-backend-api get user john_doe — natural language works too + /clerk-backend-api POST /invitations — create an invitation + +Inspect + /clerk-backend-api GET /users help — show endpoint schema without executing + /clerk-backend-api POST /invitations -h — view request/response details + +Options + --admin — bypass scope restrictions for write/delete + --version [date], version [date] — use a specific spec version + --help, -h, help — inspect endpoint instead of executing +``` + +Stop here. + +--- + +### 1. Fetch tags + +**Modes:** `browse` (when prompt is `tags` or no tag specified) — **Skip** for `help`, `execute`, and `detail`. + +If using a non-latest version, fetch tags for that version: +```bash +curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | node scripts/extract-tags.js +``` +Otherwise, use the **TAGS** already in [API specs context](#api-specs-context). + +Share tags in a table and prompt the user to select a query. + +--- + +### 2. Fetch tag endpoints + +**Modes:** `browse` (when a tag name is provided) — **Skip** for `help`, `execute`, and `detail`. + +Fetch all endpoints for the identified tag: +```bash +curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-tag-endpoints.sh "${tag_name}" +``` + +Share the results (endpoints, schemas, parameters) with the user. + +--- + +### 3. Fetch endpoint detail + +**Modes:** `execute`, `detail` — **Skip** for `help` and `browse`. + +For natural language prompts in `execute` mode, first check if the operation matches a FAST PATH entry above. If it does, skip this step and proceed directly to step 4 using the FAST PATH template. + +For other endpoints, identify the matching endpoint by searching the tags in context. Fetch tag endpoints if needed to resolve the exact path and method. + +Extract the full endpoint definition: +```bash +curl -s https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi/${version_name} | bash scripts/extract-endpoint-detail.sh "${path}" "${method}" +``` +- `${path}` — e.g. `/users/{user_id}` +- `${method}` — lowercase, e.g. `get` + +**`detail` mode:** Share the endpoint definition and schemas with the user. Stop here. + +**`execute` mode:** Continue to step 4. + +--- + +### 4. Execute request + +**Modes:** `execute` only. + +1. Run the **mandatory checks** from the CRITICAL section above. +2. Identify required and optional parameters from the spec (step 3) or FAST PATH. +3. Ask the user for any required path/query/body parameters that weren't provided. +4. Build and execute a **direct curl command** (see How to execute requests above). Do NOT use `scripts/execute-request.sh`. +5. Parse the JSON response and display it clearly. Extract and summarize key fields for the user. + +**Example — list users and parse response:** +```bash +RESPONSE=$(curl -s "https://api.clerk.com/v1/users?limit=10" \ + -H "Authorization: Bearer $CLERK_SECRET_KEY") +echo "$RESPONSE" | python3 -c " +import sys, json +data = json.load(sys.stdin) +if isinstance(data, list): + print(f'Found {len(data)} users:') + for u in data: + print(f' {u[\"id\"]}: {u.get(\"email_addresses\", [{}])[0].get(\"email_address\", \"no email\")}') +else: + print(json.dumps(data, indent=2)) +" +``` + +## See Also + +- `clerk-setup` - Initial Clerk install +- `clerk-orgs` - Manage organizations via API +- `clerk-webhooks` - Real-time event sync diff --git a/.agents/skills/clerk-backend-api/evals/evals.json b/.agents/skills/clerk-backend-api/evals/evals.json new file mode 100644 index 0000000..9013dd9 --- /dev/null +++ b/.agents/skills/clerk-backend-api/evals/evals.json @@ -0,0 +1,87 @@ +{ + "skill_name": "clerk-backend-api", + "evals": [ + { + "id": 1, + "prompt": "i need to get all users who signed up in the last 7 days from clerk's backend API. show me how", + "expected_output": "REST API call to GET /v1/users with date filter, Bearer token auth using CLERK_SECRET_KEY, response parsing and pagination handling", + "scaffold": "nextjs-basic-auth", + "files": [], + "expectations": [ + "Uses GET /v1/users endpoint", + "Includes a created_at or date-based filter query parameter to narrow to last 7 days", + "Sets CLERK_SECRET_KEY as Bearer token in the Authorization header", + "Parses the JSON response array of user objects", + "Handles or mentions pagination via limit and offset parameters" + ] + }, + { + "id": 2, + "prompt": "use the clerk backend api to create a new organization called 'Acme Corp' and invite user@example.com as an admin", + "expected_output": "Two API calls: POST /v1/organizations to create org, then POST /v1/organizations/{id}/invitations to invite with admin role", + "scaffold": "nextjs-basic-auth", + "files": [], + "expectations": [ + "Uses POST /v1/organizations to create the organization with name 'Acme Corp'", + "Uses POST /v1/organizations/{id}/invitations to send the invitation", + "Sets the role to admin (or org:admin) in the invitation payload", + "Authenticates both API calls using CLERK_SECRET_KEY in the Authorization header", + "Extracts the organization ID from the first response and uses it in the invitation request" + ] + }, + { + "id": 3, + "prompt": "i need to set custom metadata on a user via clerk's backend api. set their plan to 'pro' and onboarded to true", + "expected_output": "PATCH /v1/users/{user_id} with public_metadata or private_metadata body, explanation of metadata types and when to use each", + "scaffold": "nextjs-basic-auth", + "files": [], + "expectations": [ + "Uses PATCH /v1/users/{user_id} endpoint", + "Sets the metadata in the correct field: public_metadata, private_metadata, or unsafe_metadata", + "Explains the difference between metadata types (client-readable vs server-only vs client-writable)", + "Includes a properly formed JSON body with the plan and onboarded fields", + "Mentions checking write permissions before executing the update" + ] + }, + { + "id": 4, + "prompt": "remove a user with id user_abc123 from our clerk instance using the backend api", + "expected_output": "DELETE /v1/users/{user_id} call with warning about irreversibility, CLERK_BAPI_SCOPES check, and CLERK_SECRET_KEY auth", + "scaffold": "nextjs-basic-auth", + "files": [], + "expectations": [ + "Uses DELETE /v1/users/{user_id} endpoint with the correct user ID", + "Warns that the action is destructive and irreversible", + "Requires or recommends explicit confirmation before executing the delete", + "Includes CLERK_SECRET_KEY as Bearer token in the Authorization header", + "Mentions implications such as loss of user data, sessions, and associated records" + ] + }, + { + "id": 5, + "prompt": "i'm updating user metadata to add a 'plan' field but it keeps deleting the existing 'role' field. what am i doing wrong?", + "expected_output": "Metadata updates overwrite not merge. Read existing metadata first, spread it, then write back.", + "scaffold": "nextjs-basic-auth", + "expectations": [ + "Explains that updateUser publicMetadata replaces all existing metadata, not merges", + "Shows reading the existing user first with getUser(userId)", + "Spreads existing metadata before adding new fields ({ ...user.publicMetadata, plan: 'pro' })", + "Calls updateUser with the merged metadata object", + "Warns that this applies to publicMetadata, privateMetadata, and unsafeMetadata equally" + ] + }, + { + "id": 6, + "prompt": "my clerk backend api calls are failing with 429 errors in development. what are the rate limits?", + "expected_output": "Development has 100 req/10s limit (vs 1000/10s in production). Batch operations or reduce call frequency.", + "scaffold": "nextjs-basic-auth", + "expectations": [ + "States the development rate limit (100 requests per 10 seconds)", + "States the production rate limit (1000 requests per 10 seconds)", + "Suggests batching operations or reducing call frequency", + "Mentions that currentUser() counts as an API call against the limit", + "Recommends using auth() instead of currentUser() when only session claims are needed" + ] + } + ] +} diff --git a/.agents/skills/clerk-backend-api/scripts/api-specs-context.sh b/.agents/skills/clerk-backend-api/scripts/api-specs-context.sh new file mode 100644 index 0000000..7015d1b --- /dev/null +++ b/.agents/skills/clerk-backend-api/scripts/api-specs-context.sh @@ -0,0 +1,30 @@ +#!/usr/bin/env bash + +# Fetches all available BAPI spec versions, determines the latest, +# and extracts tags from it. Output is used as skill context. + +set -euo pipefail + +API_URL="https://api.github.com/repos/clerk/openapi-specs/contents/bapi" +RAW_BASE="https://raw.githubusercontent.com/clerk/openapi-specs/main/bapi" + +# Fetch version list, parse dates, sort, pick latest +versions=$(curl -s "$API_URL" | node -e " + let d=''; + process.stdin.on('data',c=>d+=c); + process.stdin.on('end',()=>{ + const items = JSON.parse(d) + .map(i=>i.name) + .filter(n=>/^\d{4}-\d{2}-\d{2}\.yml$/.test(n)) + .sort(); + items.forEach(n=>console.log(n)); + }); +") + +latest=$(echo "$versions" | tail -1) + +echo "AVAILABLE VERSIONS: $(echo "$versions" | tr '\n' ' ')" +echo "LATEST VERSION: $latest" +echo "" +echo "TAGS:" +curl -s "${RAW_BASE}/${latest}" | node "$(dirname "$0")/extract-tags.js" diff --git a/.agents/skills/clerk-backend-api/scripts/execute-request.sh b/.agents/skills/clerk-backend-api/scripts/execute-request.sh new file mode 100644 index 0000000..26dcb43 --- /dev/null +++ b/.agents/skills/clerk-backend-api/scripts/execute-request.sh @@ -0,0 +1,88 @@ +#!/usr/bin/env bash + +# Execute a Clerk Backend API request with scope enforcement. +# +# Usage: bash execute-request.sh [--admin] [BODY] +# +# Scope enforcement: +# GET — always allowed +# POST, PUT, PATCH — requires CLERK_BAPI_SCOPES="write" or --admin flag +# DELETE — requires CLERK_BAPI_SCOPES="write,delete" or --admin flag + +set -euo pipefail + +# Walk up from $PWD to find .env/.env.local (mirrors Clerk CLI behavior). +# Stops at the first directory that provides CLERK_SECRET_KEY. +_dir="$PWD" +while true; do + for _envfile in "$_dir/.env" "$_dir/.env.local"; do + if [[ -f "$_envfile" ]]; then + set -a + source "$_envfile" + set +a + fi + done + [[ -n "${CLERK_SECRET_KEY:-}" ]] && break + _parent="$(dirname "$_dir")" + [[ "$_parent" == "$_dir" ]] && break + _dir="$_parent" +done +unset _dir _parent _envfile + +# Parse --admin flag +ADMIN=false +if [[ "${1:-}" == "--admin" ]]; then + ADMIN=true + shift +fi + +METHOD="${1:?Usage: execute-request.sh [--admin] [BODY]}" +PATH_ARG="${2:?Usage: execute-request.sh [--admin] [BODY]}" +BODY="${3:-}" + +METHOD_UPPER=$(echo "$METHOD" | tr '[:lower:]' '[:upper:]') +SCOPES="${CLERK_BAPI_SCOPES:-}" + +# Scope check +if [[ "$ADMIN" == false ]]; then + case "$METHOD_UPPER" in + GET) + ;; # always allowed + POST|PUT|PATCH) + if [[ "$SCOPES" != *"write"* ]]; then + echo "ERROR: $METHOD_UPPER requests require CLERK_BAPI_SCOPES=\"write\" or --admin flag." >&2 + echo "Current CLERK_BAPI_SCOPES: \"$SCOPES\"" >&2 + exit 1 + fi + ;; + DELETE) + if [[ "$SCOPES" != *"write"* ]] || [[ "$SCOPES" != *"delete"* ]]; then + echo "ERROR: DELETE requests require CLERK_BAPI_SCOPES=\"write,delete\" or --admin flag." >&2 + echo "Current CLERK_BAPI_SCOPES: \"$SCOPES\"" >&2 + exit 1 + fi + ;; + *) + echo "ERROR: Unknown HTTP method: $METHOD_UPPER" >&2 + exit 1 + ;; + esac +fi + +# Base URL: use CLERK_REST_API_URL if set, otherwise default to production +BASE_URL="${CLERK_REST_API_URL:-https://api.clerk.com}" + +# Build curl command +CURL_ARGS=( + -s + -X "$METHOD_UPPER" + "${BASE_URL}/v1${PATH_ARG}" + -H "Authorization: Bearer ${CLERK_SECRET_KEY:?CLERK_SECRET_KEY is not set}" + -H "Content-Type: application/json" +) + +if [[ -n "$BODY" ]]; then + CURL_ARGS+=(-d "$BODY") +fi + +curl "${CURL_ARGS[@]}" diff --git a/.agents/skills/clerk-backend-api/scripts/extract-endpoint-detail.sh b/.agents/skills/clerk-backend-api/scripts/extract-endpoint-detail.sh new file mode 100644 index 0000000..19eb632 --- /dev/null +++ b/.agents/skills/clerk-backend-api/scripts/extract-endpoint-detail.sh @@ -0,0 +1,165 @@ +#!/usr/bin/env bash +# extract-endpoint-detail.sh +# +# Extracts full details for a specific endpoint from an OpenAPI YAML spec (stdin), +# including parameters, request body, responses, and all referenced component schemas. +# +# Usage: +# curl -s | bash extract-endpoint-detail.sh "/users/{user_id}/billing/subscription" "get" + +set -euo pipefail + +ENDPOINT="${1:?Usage: extract-endpoint-detail.sh }" +METHOD="${2:?Usage: extract-endpoint-detail.sh }" +TMPDIR_WORK=$(mktemp -d) +trap 'rm -rf "$TMPDIR_WORK"' EXIT + +SPEC="$TMPDIR_WORK/spec.yml" +cat > "$SPEC" + +node - "$ENDPOINT" "$METHOD" "$SPEC" <<'SCRIPT' +const fs = require("fs"); +const endpoint = process.argv[2]; +const method = process.argv[3].toLowerCase(); +const specFile = process.argv[4]; +const lines = fs.readFileSync(specFile, "utf8").split("\n"); + +const httpMethods = ["get", "post", "put", "patch", "delete", "options", "head"]; + +// Locate paths: and components: sections +let pathsStart = -1, pathsEnd = -1, componentsStart = -1; +for (let i = 0; i < lines.length; i++) { + if (/^paths:\s*$/.test(lines[i])) pathsStart = i; + else if (pathsStart >= 0 && pathsEnd < 0 && /^\S/.test(lines[i]) && i > pathsStart) pathsEnd = i; + if (/^components:\s*$/.test(lines[i])) componentsStart = i; +} +if (pathsEnd < 0) pathsEnd = lines.length; + +// Find the target path + method block +let targetStart = -1, targetEnd = -1; +let currentPath = null; + +for (let i = pathsStart + 1; i < pathsEnd; i++) { + const line = lines[i]; + + // Path line: exactly 2 spaces + / + if (/^ {2}\/\S/.test(line)) { + currentPath = line.trim().replace(/:$/, ""); + continue; + } + + // Method line: exactly 4 spaces + method name + const methodMatch = line.match(/^ {4}(\w+):\s*$/); + if (methodMatch && httpMethods.includes(methodMatch[1])) { + if (currentPath === endpoint && methodMatch[1] === method) { + targetStart = i; + // Find end of this method block + for (let j = i + 1; j < pathsEnd; j++) { + const nextLine = lines[j]; + // New method or new path + if (/^ {2}\/\S/.test(nextLine) || (/^ {4}\w+:\s*$/.test(nextLine) && httpMethods.some(m => nextLine.trim().startsWith(m + ":")))) { + targetEnd = j; + break; + } + } + if (targetEnd < 0) targetEnd = pathsEnd; + break; + } + } +} + +if (targetStart < 0) { + console.error(`Endpoint not found: ${method.toUpperCase()} ${endpoint}`); + process.exit(1); +} + +const blockLines = lines.slice(targetStart, targetEnd); + +// Collect all $refs from the block +const allRefs = new Set(); +for (const bl of blockLines) { + const refMatch = bl.match(/\$ref:\s*['"]?(#\/[^'"}\s]+)['"]?/); + if (refMatch) allRefs.add(refMatch[1]); +} + +// Resolve a $ref path to the raw YAML lines for that component +function resolveRef(ref) { + const parts = ref.replace("#/", "").split("/"); + // Find the component in the file by walking indentation + let searchStart = 0; + for (let p = 0; p < parts.length; p++) { + const indent = p * 2; + const target = " ".repeat(indent) + parts[p] + ":"; + let found = false; + for (let i = searchStart; i < lines.length; i++) { + if (lines[i].startsWith(target) && (lines[i] === target || lines[i][target.length] === " ")) { + searchStart = i + 1; + found = true; + break; + } + } + if (!found) return null; + } + + // Collect lines for this component (until same or lower indent) + const componentStart = searchStart - 1; + const baseIndent = parts.length * 2; + const result = []; + for (let i = searchStart; i < lines.length; i++) { + const line = lines[i]; + if (line.trim() === "") { result.push(line); continue; } + const lineIndent = line.length - line.trimStart().length; + if (lineIndent < baseIndent) break; + result.push(line); + } + return result; +} + +// Recursively resolve refs from component bodies +function collectDeepRefs(refSet, visited) { + const toProcess = [...refSet].filter(r => !visited.has(r)); + for (const ref of toProcess) { + visited.add(ref); + const body = resolveRef(ref); + if (!body) continue; + for (const bl of body) { + const refMatch = bl.match(/\$ref:\s*['"]?(#\/[^'"}\s]+)['"]?/); + if (refMatch && !visited.has(refMatch[1])) { + refSet.add(refMatch[1]); + } + } + } + // Recurse if new refs were found + const newRefs = [...refSet].filter(r => !visited.has(r)); + if (newRefs.length > 0) collectDeepRefs(refSet, visited); +} + +collectDeepRefs(allRefs, new Set()); + +// Output +console.log(`## \`${method.toUpperCase()}\` \`${endpoint}\`\n`); +console.log("### Endpoint Definition\n"); +console.log("```yaml"); +for (const bl of blockLines) { + console.log(bl); +} +console.log("```\n"); + +if (allRefs.size > 0) { + console.log(`### Referenced Components (${allRefs.size})\n`); + const sorted = [...allRefs].sort(); + for (const ref of sorted) { + const name = ref.split("/").pop(); + const category = ref.replace("#/", "").split("/").slice(0, -1).join("/"); + console.log(`#### \`${name}\` (${category})\n`); + const body = resolveRef(ref); + if (body) { + console.log("```yaml"); + for (const bl of body) console.log(bl); + console.log("```\n"); + } else { + console.log("_(could not resolve)_\n"); + } + } +} +SCRIPT diff --git a/.agents/skills/clerk-backend-api/scripts/extract-tag-endpoints.sh b/.agents/skills/clerk-backend-api/scripts/extract-tag-endpoints.sh new file mode 100644 index 0000000..5076498 --- /dev/null +++ b/.agents/skills/clerk-backend-api/scripts/extract-tag-endpoints.sh @@ -0,0 +1,208 @@ +#!/usr/bin/env bash +# extract-tag-endpoints.sh +# +# Extracts all endpoints for a given tag from an OpenAPI YAML spec (stdin), +# along with any $ref'd schemas/components. +# +# Usage: +# curl -s | bash extract-tag-endpoints.sh "Billing" + +set -euo pipefail + +TAG="${1:?Usage: extract-tag-endpoints.sh }" +TMPDIR_WORK=$(mktemp -d) +trap 'rm -rf "$TMPDIR_WORK"' EXIT + +SPEC="$TMPDIR_WORK/spec.yml" +cat > "$SPEC" + +# 1. Find all path+method blocks that have a matching tag +# Strategy: find line numbers of path entries (lines starting with " /"), +# then for each method block under that path, check if it contains the tag. + +node - "$TAG" "$SPEC" <<'SCRIPT' +const fs = require("fs"); +const tag = process.argv[2]; +const specFile = process.argv[3]; +const lines = fs.readFileSync(specFile, "utf8").split("\n"); + +const tagLower = tag.toLowerCase(); + +// Phase 1: Find all path definitions and their method blocks +// Paths start at indent 2 with " /" +// Methods start at indent 4 with " get:", " post:", etc. +const methods = ["get", "post", "put", "patch", "delete", "options", "head"]; +const endpoints = []; +const refs = new Set(); + +let currentPath = null; +let currentMethod = null; +let blockStart = -1; +let blockLines = []; +let inPaths = false; +let inComponents = false; + +// First pass: locate the "paths:" and "components:" top-level keys +let pathsStart = -1; +let pathsEnd = -1; +let componentsStart = -1; + +for (let i = 0; i < lines.length; i++) { + const line = lines[i]; + if (/^paths:\s*$/.test(line)) { + pathsStart = i; + } else if (pathsStart >= 0 && pathsEnd < 0 && /^\S/.test(line) && i > pathsStart) { + pathsEnd = i; + } + if (/^components:\s*$/.test(line)) { + componentsStart = i; + } +} +if (pathsEnd < 0) pathsEnd = lines.length; + +// Second pass: extract endpoints matching the tag +function flushBlock() { + if (!currentPath || !currentMethod || blockLines.length === 0) return; + + // Check if this block has the target tag + let inTags = false; + let hasTag = false; + const blockRefs = []; + + for (const bl of blockLines) { + const trimmed = bl.trim(); + + // Detect tags section + if (/^tags:\s*$/.test(trimmed)) { + inTags = true; + continue; + } + if (inTags) { + if (/^- /.test(trimmed)) { + const tagVal = trimmed.replace(/^- /, "").trim().replace(/^['"]|['"]$/g, ""); + if (tagVal.toLowerCase() === tagLower) hasTag = true; + } else { + inTags = false; + } + } + + // Collect $ref values + const refMatch = bl.match(/\$ref:\s*['"]?(#\/[^'"}\s]+)['"]?/); + if (refMatch) blockRefs.push(refMatch[1]); + } + + if (hasTag) { + // Extract summary, operationId, description + let summary = ""; + let operationId = ""; + let description = ""; + let params = []; + let inDesc = false; + let inParams = false; + + for (const bl of blockLines) { + const trimmed = bl.trim(); + const indent = bl.length - bl.trimStart().length; + + // Only capture operation-level keys (indent 6 = direct children of the method block) + if (indent === 6) { + const sumMatch = trimmed.match(/^summary:\s*(.+)/); + if (sumMatch) summary = sumMatch[1].replace(/^['"]|['"]$/g, ""); + + const opMatch = trimmed.match(/^operationId:\s*(.+)/); + if (opMatch) operationId = opMatch[1].replace(/^['"]|['"]$/g, ""); + + const descMatch = trimmed.match(/^description:\s*(.+)/); + if (descMatch && !inDesc) { + const val = descMatch[1].trim(); + if (val === "|-" || val === "|" || val === ">-" || val === ">") { + inDesc = true; + } else { + description = val.replace(/^['"]|['"]$/g, ""); + } + continue; + } + } + + if (inDesc) { + // Continuation lines of description — grab first non-empty line + if (!description && trimmed.length > 0) { + description = trimmed; + } + // Stop when we hit the next operation-level key + if (indent === 6 && trimmed.length > 0 && !/^description:/.test(trimmed)) { + inDesc = false; + } + } + } + + endpoints.push({ + method: currentMethod.toUpperCase(), + path: currentPath, + operationId, + summary, + description, + refs: blockRefs, + }); + + for (const r of blockRefs) refs.add(r); + } +} + +for (let i = pathsStart + 1; i < pathsEnd; i++) { + const line = lines[i]; + + // Path line: exactly 2 spaces + / + if (/^ {2}\/\S/.test(line)) { + flushBlock(); + currentPath = line.trim().replace(/:$/, ""); + currentMethod = null; + blockLines = []; + continue; + } + + // Method line: exactly 4 spaces + method name + const methodMatch = line.match(/^ {4}(\w+):\s*$/); + if (methodMatch && methods.includes(methodMatch[1])) { + flushBlock(); + currentMethod = methodMatch[1]; + blockLines = []; + continue; + } + + if (currentMethod) { + blockLines.push(line); + } +} +flushBlock(); + +// Output endpoints +if (endpoints.length === 0) { + console.error(`No endpoints found for tag: "${tag}"`); + process.exit(1); +} + +console.log(`## Endpoints for "${tag}" (${endpoints.length} total)\n`); +for (const ep of endpoints) { + console.log(`### \`${ep.method}\` \`${ep.path}\``); + if (ep.operationId) console.log(`- **operationId**: \`${ep.operationId}\``); + if (ep.summary) console.log(`- **summary**: ${ep.summary}`); + if (ep.description && ep.description !== ep.summary) + console.log(`- **description**: ${ep.description}`); + if (ep.refs.length > 0) { + console.log(`- **refs**: ${ep.refs.map(r => "\`" + r.split("/").pop() + "\`").join(", ")}`); + } + console.log(); +} + +// Output unique refs list +if (refs.size > 0) { + console.log(`## Referenced Components (${refs.size} unique)\n`); + const sorted = [...refs].sort(); + for (const r of sorted) { + const name = r.split("/").pop(); + const category = r.split("/").slice(0, -1).join("/").replace("#/", ""); + console.log(`- \`${name}\` (${category})`); + } +} +SCRIPT diff --git a/.agents/skills/clerk-backend-api/scripts/extract-tags.js b/.agents/skills/clerk-backend-api/scripts/extract-tags.js new file mode 100644 index 0000000..b1a4fb2 --- /dev/null +++ b/.agents/skills/clerk-backend-api/scripts/extract-tags.js @@ -0,0 +1,14 @@ +let input = ""; +process.stdin.on("data", d => input += d); +process.stdin.on("end", () => { + const lines = input.replace(/\r/g, "").split("\n"); + let inTags = false; + for (const line of lines) { + if (line === "tags:") { inTags = true; continue; } + if (inTags && line.length > 0 && line[0] !== " ") break; + if (inTags) { + const m = line.match(/^\s{2}- name:\s*(.+)/); + if (m) console.log(m[1]); + } + } +}); diff --git a/.agents/skills/clerk-cli/SKILL.md b/.agents/skills/clerk-cli/SKILL.md new file mode 100644 index 0000000..80dc6ba --- /dev/null +++ b/.agents/skills/clerk-cli/SKILL.md @@ -0,0 +1,262 @@ +--- +name: clerk-cli +description: >- + Operate the Clerk CLI (`clerk` binary) for authentication, user/org/session management, + deploy verification, instance config, env keys, and any Clerk Backend or Platform API + call. Use when the user mentions Clerk management tasks, "list clerk users", "create a + clerk user", "update organization", "pull clerk config", "clerk env pull", + "clerk doctor", "clerk deploy", "clerk deploy status", "clerk api", or any ad-hoc + Clerk API request. Prefer the CLI over raw HTTP: it handles auth, key resolution, + app/instance targeting, and formatting automatically. +license: MIT +--- + +# Clerk CLI + +The `clerk` binary is a pre-authenticated gateway to Clerk's Backend API and Platform API, plus project-level tooling (auth, linking, env pulls, instance config). When the user asks anything that touches a Clerk resource, reach for `clerk` first instead of hand-rolling `curl`. + +> This skill targets clerk `latest`. If `clerk --version` disagrees with the latest available CLI, refresh it with `clerk skill install` or a package runner such as `bunx clerk@latest`. The binary is always the source of truth, so run `clerk --help` to verify anything this skill claims. + +## Execution environment (prefer the host, understand the sandbox warning) + +Most AI coding agents default to running shell commands in a sandbox where the +user's home directory, OS keychain, browser launch, localhost callback +binding, or network access may be blocked. The Clerk CLI depends on all of +those host capabilities: + +- **OS credential store**: `clerk auth login` stores the OAuth token in the + system keychain. A sandbox without keychain access reports "not logged in" + even when the host is authenticated. +- **Home-directory Clerk state**: saved config, cached metadata, and fallback + credentials live under the user's Clerk config/data directories. +- **Linked project metadata**: resolved from the repo's git remote plus Clerk + config. Sandboxes with stripped repo state or blocked home-dir reads can + misreport "not linked". +- **Local `.env*` files**: publishable and secret keys materialized by + `clerk env pull`. +- **Outbound network access to Clerk**: every Backend and Platform API call. +- **Browser + localhost OAuth callback**: `clerk auth login` needs both. + +In agent mode, the CLI now does a **best-effort warn-once check** at the +host-sensitive library boundaries. When it detects that host-only Clerk state +or system capabilities are unavailable, it emits: + +```text +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. +``` + +Treat that warning as authoritative. The command may continue, but any auth, +link, env, config, API, browser, or OAuth callback failure from that +invocation is untrusted until you rerun the same command on the host. + +**Prefer these commands on the user's host shell, not in a sandbox:** + +`clerk doctor`, `clerk whoami`, `clerk auth login`, `clerk link`, `clerk env pull`, +`clerk apps ...`, `clerk config ...`, `clerk api ...`. + +If a command was accidentally run in a sandbox and it reports `Not logged in`, +`auth_required`, `not linked`, missing env, keychain/file permission errors, +or network failures, **do not treat the result as authoritative**. Rerun it on +the host before acting on it or reporting it to the user. + +## Invoking the CLI + +Before running any `clerk` command, figure out which binary to invoke and bind that choice for the rest of the session: + +```sh +# 1. Prefer a globally installed binary when it matches the skill's target version. +command -v clerk >/dev/null 2>&1 && clerk --version +``` + +If that prints `latest` or any version you trust, use bare `clerk` for the rest of the session. + +Otherwise fall back to a package runner, in this order (matches the CLI's own `preferredRunner` logic, which prefers the runner that matches the project's lockfile): + +| Project package manager | 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) has no `dlx`; treat those projects as "no preferred runner" and fall back to the first runner from the list above that's on PATH. + +The published npm package is **`clerk`**, not `@clerk/cli`. Never teach `npm install -g clerk` as the primary path. If the global CLI is stale or behaves differently from this skill, either upgrade the global install or fall back to the `latest` runner form above. + +## Prerequisites (run at session start) + +Before running any other Clerk command in a session, verify the CLI is authenticated, linked, and healthy: + +```sh +clerk --version # confirm the binary is on PATH +clerk doctor --json # structured health check; exit 1 if anything failed +``` + +**Always run `clerk doctor --json` first.** It catches the common setup failures (not logged in, project not linked, missing keys, stale CLI version) up front, so later commands don't fail with confusing errors. In agent mode it also includes a `Host execution` check that warns when Clerk's host-side config / credential directories are not writable, which is the canonical signal that the current invocation is likely sandboxed. + +Each result has `name`, `status` (`pass`/`warn`/`fail`), `message`, optional `detail`, optional `remedy` (how to fix it), and optional `fix` (label for auto-fixable issues). Parse that and act on it, or surface it to the user. If `Host execution` warns, rerun the command on the host before trusting any auth/link/env/API failures from the same sandboxed run. Rerun `clerk doctor --json` whenever a later command starts misbehaving. + +If `clerk --version` reports a newer CLI than this skill covers, trust `clerk --help` first and refresh this skill bundle from its source. + +## The mental model + +| Layer | What it does | Commands | +| ------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | +| **Session / project** | Auth, link a repo to a Clerk app, pull env keys | `auth login`, `link`, `unlink`, `whoami`, `env pull`, `doctor` | +| **Instance config** | Manage the configuration (social providers, session lifetimes, etc.) for a specific instance | `config pull`, `config schema`, `config patch`, `config put` | +| **Backend API (default)** | Runtime data: users, orgs, sessions, invitations, JWT templates, webhooks | `clerk api ` | +| **Platform API (`--platform`)** | Account-level: applications, instances, billing | `clerk api --platform ` | + +A project is "linked" to an application via `clerk link`. Once linked, most commands auto-resolve the target app and dev instance from the repo's git remote. To target something else, pass `--app ` and/or `--instance dev|prod|`. See [references/auth.md](references/auth.md) for the full resolution order. + +## Discover endpoints - don't memorize them + +The CLI ships with the Clerk OpenAPI catalog. Always discover endpoints dynamically instead of guessing paths: + +```sh +clerk api ls # list every Backend API endpoint +clerk api ls users # filter by keyword (matches path, summary, tag, operationId) +clerk api ls --platform apps # list Platform API endpoints +``` + +Use this before `clerk api `. If you don't see the endpoint you expected, it probably isn't exposed. + +## The `clerk api` command (the workhorse) + +`clerk api` makes authenticated HTTP calls. It auto-resolves keys, auto-detects method from body presence, supports stdin, and can preview mutations with `--dry-run`. + +```sh +# GET requests +clerk api /users # list users +clerk api /users/user_abc123 # fetch one +clerk api /users?limit=5&order_by=-created_at # query params work inline + +# Mutating requests +clerk api /users -d '{"email_address":["a@b.co"]}' # POST (auto-detected from body) +clerk api /users/user_abc123 -X PATCH -d '{"first_name":"A"}' +clerk api /users/user_abc123 -X DELETE + +# Body from file or stdin +clerk api /users --file payload.json +cat payload.json | clerk api /users + +# Always preview mutations first +clerk api /users/user_abc123 -X DELETE --dry-run +clerk api /users/user_abc123 -X DELETE --yes # skip confirmation once you've verified + +# Target a specific app/instance +clerk api /users --app app_abc123 --instance prod + +# Include response headers when debugging +clerk api /users --include + +# Platform API (account-level, not tenant data) +clerk api /v1/platform/applications --platform +``` + +For instance config, prefer the dedicated `clerk config ...` commands over raw Platform API `/config` paths. They handle dry-run, diffing, and confirmation more cleanly than the raw endpoint form. + +**Always `--dry-run` a mutation before running it for real.** Then re-run without `--dry-run` (add `--yes` if you're sure). In agent mode, interactive confirmation is bypassed, so `--dry-run` is the only safety net for destructive calls. + +**JSON bodies must be valid JSON.** The CLI validates and rejects malformed payloads. + +**Endpoint paths may be given with or without `/v1/` prefix** - both work for Backend API calls. The CLI normalizes. + +See [references/recipes.md](references/recipes.md) for concrete patterns: listing/filtering users, creating orgs, impersonation sessions, etc. + +## Inspecting large outputs (do not flood your context) + +`users list`, `apps list`, `config pull`, and most `clerk api` GETs return payloads that can be many kilobytes or megabytes. Production tenants commonly have thousands of users; an instance config can be hundreds of fields deep. Reading those responses into the conversation costs context window for no benefit. Save the response to a file first, then query just what you need with `jq`: + +```sh +# 1. Persist the response. Use --limit 250 to maximize page size for 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. Inspect only what you need. +jq '.data | length' /tmp/users.json # current page size +jq '.hasMore' /tmp/users.json # are more pages available? +jq '.data[0] | keys' /tmp/users.json # discover the user shape once +jq '.data[] | {id, email_addresses}' /tmp/users.json # project to a few fields +jq '[.data[] | select(.banned)] | length' /tmp/users.json # aggregate without reading rows +``` + +**If `jq` is not available**, fall back to Python or Node - both can stream the file without printing it whole: + +```sh +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` the file only when you genuinely need to see the raw structure for one-off debugging. When walking pages, write each page to its own file (e.g. `page-${offset}.json`) so individual pages stay independently inspectable. + +## Core commands at a glance + +| Command | Purpose | Key flags | +| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `clerk init` | Scaffold Clerk into a project. `--starter` only supports bootstrap for Next.js, React Router, Astro, Nuxt, TanStack Start, React, Vue, and JavaScript. | `--framework`, `--pm`, `--name` (with `--starter`), `--app`, `--starter`, `-y`, `--no-skills` | +| `clerk auth login` | OAuth browser login (stores token). Agent mode: no-op if already logged in. With no stored session it still opens a browser and binds a localhost callback, so it is not unattended; prefer `CLERK_PLATFORM_API_KEY` for headless flows. Aliases: `signup`, `signin`, `sign-in`. Top-level shortcut: `clerk login`. | - | +| `clerk auth logout` | Clear stored credentials. Aliases: `signout`, `sign-out`. Top-level shortcut: `clerk logout`. | - | +| `clerk whoami` | Print the logged-in email. | - | +| `clerk link` / `clerk unlink` | Link this repo to a Clerk app, or remove the link. `unlink` requires `--yes` in agent mode. | (see `--help`) | +| `clerk env pull` | Write publishable + secret keys to the framework's env file (merge, not clobber). Resolves `.env.development.local` → framework-preferred file → `.env.local`; override with `--file`. | (see `--help`) | +| `clerk config {pull,schema}` | Fetch instance config JSON, or its JSON Schema. | (see `--help`) | +| `clerk config patch` | Partial update (PATCH) of instance config. Pass `--destructive` to actually delete sub-resources touched by the patch rather than resetting them to defaults. | `--app`, `--instance`, `--file`, `--json`, `--dry-run`, `--yes`, `--destructive` | +| `clerk config put` | Full replacement (PUT) of instance config. Pass `--destructive` to actually delete removed sub-resources rather than resetting them to defaults. | `--app`, `--instance`, `--file`, `--json`, `--dry-run`, `--yes`, `--destructive` | +| `clerk apps {list,create}` | List or create Clerk applications. Defaults to JSON in agent mode. | (see `--help`) | +| `clerk users` (no subcommand) | Interactive picker for `users` actions in human mode; in agent mode prints the action list and exits `2`. Always pass an explicit subcommand from agents. | `--app`, `--instance`, `--secret-key` | +| `clerk users list` | List users via curated BAPI flags. JSON output (default when piped or in agent mode) is `{data, hasMore}` so callers can paginate without `/users/count`. `--limit` defaults to 100 (max 250). | `--limit`, `--offset`, `--query`, `--email-address`, `--phone-number`, `--username`, `--user-id`, `--external-id`, `--order-by`, `--json`, `--app`, `--instance`, `--secret-key` | +| `clerk users create` | Create a user from curated flags or a raw BAPI body. Confirmation prompt unless `--yes`. | `--email`, `--phone`, `--username`, `--password`, `--first-name`, `--last-name`, `--external-id`, `-d, --data`, `--file`, `--dry-run`, `--yes`, `--json` | +| `clerk users open [user-id]` | Open a user's dashboard page. Agent mode requires `user-id` and prints a JSON descriptor instead of launching a browser. | (see `--help`) | +| `clerk open [subpath]` | Open the linked app's dashboard in a browser. Agent mode: prints a JSON descriptor instead of opening. | (see `--help`) | +| `clerk deploy` | Human-mode production deploy wizard. Agent mode: emits a read-only JSON handoff and tells the agent whether to ask the human to run the wizard, wait for provisioning, finish OAuth, or do nothing. | `--mode agent`, `--mode human`, `--verbose` | +| `clerk deploy status` | Read-only deploy verification. Triggers a DNS check, reports aggregate domain and OAuth readiness, and exits `0` only when complete. Agent mode does one quick check by default; pass `--wait` to keep waiting. | `--mode agent`, `--wait`, `--verbose` | +| `clerk doctor` | Health check (CLI version, login, link, env, config, completion; plus host-execution probe in agent mode). | `--json`, `--spotlight`, `--verbose`, `--fix` | +| `clerk api [path]` | Authenticated HTTP to Backend/Platform API. | `-X`, `-d`, `--file`, `--dry-run`, `--yes`, `--include`, `--app`, `--secret-key`, `--instance`, `--platform` | +| `clerk api ls [filter]` | Discover endpoints from the bundled OpenAPI catalog. | (see `--help`) | +| `clerk completion [shell]` | Print a shell completion script (`bash`, `zsh`, `fish`, `powershell`). | - | +| `clerk update` | Update the CLI to the latest version. | `--channel`, `-y`, `--all` | +| `clerk skill install` | Reinstall the bundled `clerk-cli` skill from the CLI. In this standalone bundle, update the skill source directly instead. | (see `--help`) | + +**`clerk --help` is the source of truth for flags.** This table is a hint, not a spec. Before running an unfamiliar command or flag combination, run `clerk --help` once per session. Every command also defines `setExamples([...])` in source, which `--help` renders as a copy-pasteable Examples block, so you rarely need to guess syntax. + +## Agent-mode behavior (important) + +The CLI auto-detects agent mode when stdout is not a TTY, or when `--mode agent` / `CLERK_MODE=agent` is set. In agent mode: + +- **Interactive prompts are disabled.** Commands that would normally show pickers (`link` without `--app`, `unlink` without `--yes`, `users` without a subcommand) either auto-resolve or exit with a usage error. `clerk api` with no args prints usage guidance and exits 0; pass an endpoint (or `ls`) explicitly. Always pass explicit flags (`--app`, `--yes`) in scripted calls. +- **Host-sensitive operations emit a sandbox warning once per invocation.** Home-directory Clerk state, keychain access, networked Clerk calls, browser launch, and localhost OAuth callback setup can trigger the warning shown above. If it appears, rerun the same command on the host before trusting the result. +- **If your harness does not clearly present as agent mode, force it.** Use `--mode agent` or `CLERK_MODE=agent` when you want the CLI's non-interactive behavior and sandbox warning path to apply deterministically. +- **`link` supports deterministic agent flows.** In agent mode, `clerk link --app ` links directly. Without `--app`, the CLI will try silent key-based autolink first; if it cannot determine the app unambiguously, it exits and tells you to pass `--app`. +- **`init` never selects or creates a real Clerk app for you in agent mode unless authenticated or given a target.** Pass `--app ` (or pre-link the project) to authenticate and link a real app, or pass `--keyless` to use auto-generated temporary development keys when bootstrapping a new project on a keyless-capable framework. Without either, agent mode prints manual setup guidance and exits cleanly. +- **`unlink` requires `--yes` in agent mode.** This preserves the same safety bar as other destructive commands while still letting an agent complete the unlink non-interactively. +- **Mutations still require `--yes`** unless you accept per-call confirmation is impossible. +- **`doctor --fix` is ignored.** Parse `doctor --json` output's `remedy` field and act on it yourself. +- **`apps list` and `apps create` default to JSON** when piped. +- **`users` defaults to JSON when piped, like `apps`.** `clerk users list` and `clerk users create` emit JSON in agent mode. Bare `clerk users` (no subcommand) is a usage error in agent mode - pass `list`, `create`, or `open` explicitly. `clerk users open` requires the `user-id` positional in agent mode and prints a JSON descriptor instead of launching a browser. +- **`deploy` has an agent handoff plus a verification gate.** In agent mode, bare `clerk deploy` is read-only and emits a JSON handoff. It never drives the interactive wizard. Do not tell Claude or another agent to run `! clerk deploy`, because the wizard needs interactive stdin prompts. Ask the human to run `clerk deploy` in a new terminal window when needed, then run `clerk deploy status --mode agent` to verify completion. See [references/agent-mode.md](references/agent-mode.md#deploy-handoff-and-verification). +- **`--input-json `** expands JSON into flags on any command (e.g. `clerk init --input-json '{"framework":"next","yes":true}'`). Piped stdin is also accepted: `echo '{"yes":true}' | clerk init`. Place `--input-json` after the leaf subcommand. Full rules in [references/agent-mode.md](references/agent-mode.md#passing-options-as-json---input-json). + +Full matrix and sandbox details in [references/agent-mode.md](references/agent-mode.md). + +## Output format and errors + +- **JSON output:** `--json` on `apps list` and `doctor`. For `clerk api`, the response body is the raw API JSON, so pipe into `jq` freely. +- **Exit codes:** `0` success, `1` runtime error, `2` usage/validation error. `doctor` returns `1` if any check failed. +- **Error format:** User-facing errors print a single line to stderr and set a non-zero exit code. Use `--verbose` for stack traces when debugging. + +## Safety rules for autonomous use + +1. **Discover before acting:** `clerk api ls ` before `clerk api `. +2. **Preview mutations:** `--dry-run` on every `config patch`, `config put`, `api -X POST/PATCH/PUT/DELETE`. +3. **Target explicitly in production:** pass `--instance prod` rather than relying on defaults, and confirm with the user before any production mutation. +4. **Never commit secrets:** `env pull` writes to `.env.local` (which should be gitignored). Don't paste secret keys into code or chat. +5. **Use `doctor --json`** to diagnose before assuming the CLI is broken. + +## References + +- [references/auth.md](references/auth.md) - auth flow, key resolution order, host-vs-sandbox behavior, `--app`/`--instance` targeting, Backend vs Platform API. +- [references/recipes.md](references/recipes.md) - copy-pasteable recipes for common Clerk tasks. +- [references/agent-mode.md](references/agent-mode.md) - agent-mode behavior matrix, sandbox warning semantics, exit codes, error format. diff --git a/.agents/skills/clerk-cli/references/agent-mode.md b/.agents/skills/clerk-cli/references/agent-mode.md new file mode 100644 index 0000000..7ed4c88 --- /dev/null +++ b/.agents/skills/clerk-cli/references/agent-mode.md @@ -0,0 +1,287 @@ +# Clerk CLI - Agent Mode Reference + +The Clerk CLI has a first-class "agent" mode that's designed for non-interactive and AI-driven use. Read this before writing scripts or letting an LLM drive the CLI. + +## Sandbox warning semantics + +Agent mode and sandboxing are related but not identical: + +- **Agent mode** controls non-interactive behavior. +- **Sandboxing** controls whether the CLI can actually reach host-only Clerk + state and host system capabilities. + +In agent mode, the CLI now performs a **best-effort warn-once check** at the +host-sensitive integration boundaries. The first time an invocation hits a +blocked host capability, it emits: + +```text +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. +``` + +Treat that warning as authoritative. The command may still continue and return +an ordinary Clerk error, but any auth/link/env/config/API/browser/OAuth +failure from that invocation should be treated as suspect until rerun on the +host. + +The warning can be triggered by: + +- home-directory Clerk config / credential file access +- OS keychain access +- outbound Clerk network requests +- browser launch +- localhost callback server binding for OAuth + +If your harness does not obviously look non-interactive, force agent behavior +with `--mode agent` or `CLERK_MODE=agent` so the CLI's non-interactive and +sandbox-warning paths apply deterministically. + +## How agent mode is detected + +Priority (first match wins): + +1. `--mode agent` flag on the command line +2. `CLERK_MODE=agent` environment variable +3. Stdout is not a TTY (piped, redirected, or running under an agent harness) + +Force human mode with `--mode human` or `CLERK_MODE=human`. Typical AI-agent invocations automatically land in agent mode because stdout is piped. + +## What changes in agent mode + +| Behavior | Human mode | Agent mode | +| ---------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Interactive pickers (`link` without `--app`, `api` with no args) | Show a TUI picker | Print structured guidance and exit, or auto-resolve | +| `clerk link --app ` | Links directly | Links directly | +| `clerk link` without `--app` | Interactive picker / create UI | Tries silent autolink from detected publishable keys; if no deterministic match exists, exits with a usage error telling the caller to pass `--app` | +| Confirmation prompts (`unlink`, `config patch`, `api -X DELETE`) | Prompt y/n | Require `--yes`, otherwise error | +| `clerk doctor --fix` | Interactively offers fixes | **Ignored**; output the `remedy` field and let the caller act | +| `clerk apps list` default output | Table | JSON (when piped) | +| `clerk apps create ` output | Human-readable summary | JSON (auto-detected, same as `apps list`); `--json` also works explicitly | +| `clerk users list` / `clerk users create` default output | Table / human-readable | JSON (auto-detected when piped); `--json` also works explicitly | +| `clerk users` (no subcommand) | Interactive action picker | Prints the action list and exits with a usage error (code `2`) - pass `list` / `create` / `open` | +| `clerk users open [user-id]` | Picks a user interactively, opens browser | Requires `user-id`; prints `{url, appId, appName, instanceId, instanceLabel, userId, opened: false}` and does not open a browser | +| `clerk open [subpath]` | Opens the browser to the URL | Does not open a browser. Prints a JSON descriptor (`{url, appId, appName, instanceId, instanceLabel, subpath, opened: false}`) on stdout so the agent can surface it | +| `clerk deploy` | Interactive production deploy wizard | Read-only handoff. Emits deploy status JSON on stdout and exits `0` for linked projects. Does not prompt, mutate, trigger DNS checks, or poll. | +| `clerk deploy status` | Verify production deploy state | Read-only verification gate. Triggers one DNS check for active production domains, waits briefly, reads one live status snapshot, emits status JSON on stdout, exits `0` when complete and `1` when incomplete. It does not keep waiting or back off in agent mode unless `--wait` is passed. Use `--wait` when the user asks the agent to keep waiting for DNS, SSL, email DNS, or final Clerk-side readiness. | +| `clerk auth login` when already authenticated | Prompt to re-auth | Silent no-op | +| `clerk init` | Full interactive scaffold flow | Runs non-interactively. Explicit `--app` or a linked profile uses the real-app auth/link/env flow; without it, an authenticated agent on a keyless-capable framework creates a real app and links it. Pass `--keyless` to opt into auto-generated dev keys for new projects on keyless-capable frameworks. Without `--keyless`, an unauthenticated agent (or non-keyless framework with no app target) prints manual setup guidance. | +| Color / spinners | Enabled | Disabled | + +In addition, sandboxed agent-mode invocations may emit the warning above once +per CLI invocation when a host-sensitive operation is blocked. + +**Rule of thumb:** always pass `--yes` for mutations and `--json` for structured output where available. Pass `--app` / `--instance` when you intentionally target a real app; pass `--keyless` to opt into auto-generated dev keys when bootstrapping a new project without authenticating. + +## Passing options as JSON: `--input-json` + +Every command accepts `--input-json `. Keys convert from camelCase/snake_case to kebab-case and expand into flags before Commander parses argv - so anything a command accepts as a flag can come from JSON instead. + +```sh +clerk init --input-json '{"framework":"next","yes":true}' +clerk config pull --input-json '{"keys":["auth_email","session"]}' # arrays → repeated flags +clerk init --input-json @init-opts.json # read JSON from a file +clerk init --input-json - # read JSON from stdin +echo '{"framework":"next","yes":true}' | clerk init # auto-detect piped stdin +``` + +When `--input-json` is omitted and stdin is piped (not a TTY), the CLI automatically reads JSON from stdin - no flag needed. This lets agents pipe options directly: `echo '{"yes":true}' | clerk init`. + +Positional arguments (e.g. the `` in `clerk apps create `) cannot come from JSON - only flag-style options can. + +| JSON | Expansion | +| ---------------- | --------------------------------------- | +| `"str"` / number | `--flag ` | +| `true` | `--flag` | +| `false` / `null` | omitted | +| `["a","b"]` | `--flag a --flag b` (empty arrays omit) | +| `{…}` (nested) | rejected - `invalid_json`, exit `2` | + +**Placement.** Put `--input-json` after the leaf subcommand. Before it, flags land on the root program, so only `--mode` / `--verbose` work there - subcommand flags (`--json`, `--app`, etc.) error as unknown. Explicit flags after `--input-json` override its values (last-flag-wins). + +Errors use the standard agent-mode format: bad JSON → `invalid_json`, missing `@file` → `file_not_found`, unknown expanded flags → Commander's `unknown option`. All exit `2`. + +## Exit codes + +| Code | Meaning | +| ---- | ---------------------------------------------------------------------------- | +| `0` | Success | +| `1` | Runtime error (auth failure, API error, file I/O, etc.) | +| `2` | Usage or validation error (bad flags, malformed JSON body, unknown endpoint) | + +`clerk doctor` exits `1` when any check fails (warnings alone still exit `0`). + +## Error output format + +**Human mode:** + +- Single-line error message on stderr. +- Stack traces hidden unless `--verbose` is passed. +- API errors include the first message from the response body, prefixed with a human context string (e.g., `Failed to fetch config: unauthorized`). + +**Agent mode:** + +- Structured JSON on stderr: `{"error":{"code":"...","message":"...","docsUrl?":"...","errors?":[...]}}`. +- `code` is a machine-readable error code (e.g., `auth_required`, `api_error`, `unexpected_error`). +- `errors` array is present for API errors and mirrors the Clerk API error shape (`{code?, message?, meta?}`). +- `docsUrl` is present when the error has associated documentation. + +**Both modes:** + +- User-aborted commands exit cleanly with no error output. +- When handling errors programmatically, read stderr, check the exit code, and re-run with `--verbose` to get a trace if you need to debug. + +## Structured outputs you can rely on + +| Command | Structured output | +| --------------------------------------------- | --------------------------------------------------------------------------------------------- | +| `clerk doctor --json` | `[{name, status, message, detail?, remedy?, fix?}]` | +| `clerk apps list --json` | Array of application objects | +| `clerk apps create --json` | Single application object | +| `clerk users list` (agent mode or `--json`) | `{data: [...users], hasMore}` envelope (BAPI user shape inside `data`) | +| `clerk users create` (agent mode or `--json`) | Single user object (raw BAPI shape) | +| `clerk users open` (agent mode) | `{url, appId, appName, instanceId, instanceLabel, userId, opened: false}` | +| `clerk api ` | Raw API JSON (Backend or Platform) on stdout | +| `clerk api --include` | Response headers on stderr, body on stdout | +| `clerk config pull` | Instance config JSON | +| `clerk config schema` | JSON Schema | +| `clerk open [subpath]` | `{url, appId, appName, instanceId, instanceLabel, subpath, opened: false}` (agent mode) | +| `clerk open --print` | Plain dashboard URL on stdout | +| `clerk deploy` (agent mode) | Deploy handoff report with `complete`, `state`, domain status, OAuth status, and `nextAction` | +| `clerk deploy status` (agent mode) | Deploy verification report with the same shape, plus exit `0` complete or `1` incomplete | +| Any command (agent mode) | On error: `{"error":{"code","message","docsUrl?","errors?"}}` on stderr | + +For commands without an explicit `--json` flag, `clerk api` is your escape hatch: hit the underlying endpoint directly. + +## Patterns for agent-driven use + +### Diagnose before acting + +```sh +clerk doctor --json --spotlight +``` + +Parse the output, then for each failing check read `remedy` and act. Never call `--fix` from an agent - it's interactive. + +In agent mode, `doctor` also includes a **`Host execution`** check when it can +detect that Clerk's host-side state is not writable. If that check warns, stop +trusting auth/link/env/API failures from the same sandboxed run and rerun the +relevant command on the host. + +### Preview every mutation + +```sh +# Dry run first +clerk api /users/user_abc123 -X DELETE --dry-run +# If the preview is what you expected, run it with --yes +clerk api /users/user_abc123 -X DELETE --yes +``` + +### Target explicitly + +```sh +# Don't rely on the linked profile for critical operations +clerk api /users --app app_abc123 --instance prod +``` + +The same advice applies to linking in agent mode: `clerk link --app app_abc123` is deterministic and works non-interactively. If you omit `--app`, the command only succeeds when silent autolink can prove the target app from existing publishable keys. + +### Deploy handoff and verification + +Do not try to drive the interactive deploy wizard from an agent. Use the handoff and check commands instead. + +```sh +# 1. Inspect current production deploy state without mutating anything. +clerk deploy --mode agent + +# 2. If the handoff says a human action is needed, ask the user to run this +# in a new terminal window, not through `! clerk deploy`: +clerk deploy --mode human + +# 3. After the user finishes or DNS has had time to propagate, verify: +clerk deploy status --mode agent + +# 4. If the user asks you to keep waiting, use the retrying wait loop: +clerk deploy status --mode agent --wait +``` + +`clerk deploy --mode agent` is read-only. It resolves the linked app and current production deploy snapshot, then emits JSON on stdout. It does **not** trigger DNS checks, poll, create production instances, patch OAuth config, or prompt. Linked projects exit `0` because this is an informational handoff. Not-linked and API failures still use the normal agent error envelope on stderr. + +Never try to run the human wizard through Claude's `! clerk deploy` shell escape or any non-interactive agent shell. The deploy wizard asks for domain, DNS export, OAuth, and verification inputs over stdin, so it needs a real human terminal. Tell the user to open a new terminal window in the project directory and run `clerk deploy` or `clerk deploy --mode human` there. After they finish, return to agent mode and run `clerk deploy status --mode agent`. + +`clerk deploy status --mode agent` is the gate. It is also read-only with respect to deploy configuration, but for an active production domain it triggers one Clerk DNS check, waits briefly, reads a live status/config snapshot, then reports DNS, SSL, email DNS, aggregate domain readiness, and OAuth completeness. By default it does not keep waiting or exponentially back off in agent mode. If the check is incomplete and the user asks the agent to continue waiting, run `clerk deploy status --mode agent --wait` instead of manually sleeping and retrying. `--wait` uses the shared poll loop: one immediate status read, then up to 5 exponential-backoff retries until aggregate domain status is complete. It emits the same status JSON. It exits: + +| Exit | Meaning | +| ---- | ------------------------------------------------------------------------------------ | +| `0` | Deploy is complete and verified. | +| `1` | The check ran successfully, but deploy is incomplete. Read `state` and `nextAction`. | +| else | A real CLI error occurred. Read the standard agent error envelope on stderr. | + +Deploy-specific agent errors still use the standard envelope and may include typed codes such as `plan_insufficient`, `provider_domain_not_allowed`, `home_url_taken`, or `form_param_invalid`. + +When a production instance exists, `nextAction` includes the full Clerk Dashboard domains URL so agents can send the user directly to the same page the human CLI prints in its next steps. Always show that URL to the user. Ask whether they want you to open it for them instead of omitting or paraphrasing it away. + +The deploy report has this shape: + +```json +{ + "complete": false, + "state": "domain_pending", + "domain": "example.com", + "productionInstanceId": "ins_...", + "domainStatus": { "dns": "complete", "ssl": "pending", "mail": "complete" }, + "pendingDnsRecords": [{ "type": "CNAME", "host": "clerk.example.com", "value": "..." }], + "oauth": { "complete": true, "configured": ["google"], "pending": [], "unsupported": [] }, + "nextAction": "SSL still provisioning for example.com. Re-run `clerk deploy status` in a few minutes, DNS propagation can take time. Ask the user to visit the Clerk Dashboard domains page, or offer to open it: https://dashboard.clerk.com/apps/app_.../instances/ins_.../domains" +} +``` + +`complete` is `true` only when the aggregate domain status is complete and all supported OAuth providers enabled in development have production credentials. The `domainStatus` object is a component summary; DNS, SSL, and email DNS can all read `complete` while `state` remains `domain_pending` if Clerk-side finalization is still pending. + +State precedence: + +| State | What to do | +| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- | +| `not_started` | Ask the human to run `clerk deploy --mode human`, then run `clerk deploy status --mode agent`. | +| `domain_provisioning` | Wait briefly or ask the human to finish `clerk deploy`, then run `clerk deploy status --mode agent`. | +| `domain_pending` | Surface `pendingDnsRecords` when present. Re-run `clerk deploy status --mode agent` after DNS, SSL, or email DNS propagation. | +| `oauth_pending` | Ask the human to finish the OAuth credential steps in `clerk deploy --mode human`, then verify with `deploy status`. | +| `complete` | No action needed. | + +Unsupported OAuth providers do not block `complete`, because the wizard cannot configure them automatically. They are still surfaced in `oauth.unsupported` so you can warn the user to review them in the Clerk Dashboard. + +### Use the catalog, not hard-coded paths + +```sh +clerk api ls users # discover available user endpoints +clerk api ls --platform apps # platform-side endpoints +``` + +### Surface doctor remedies to the user + +When `clerk doctor --json` reports a failure, show the user the `name`, `message`, and `remedy` - don't just silently try to fix it, because the underlying fix (e.g., `clerk auth login`) usually requires human interaction. + +`clerk doctor --fix` is disabled in agent mode, so you cannot rely on it. If a caller wants to attempt remediation anyway, map the failing check to the command that would fix it in human mode. Each check exposes this mapping via the optional `fix.label` field on the JSON result: + +| Failing check | Manual remediation | +| ----------------------- | -------------------------------------------- | +| `Logged in` | `clerk auth login` | +| `Authentication valid` | `clerk auth login` | +| `CLI configuration` | `clerk auth login` | +| `Project linked` | `clerk link` | +| `Application reachable` | `clerk link` | +| `Instance IDs` | `clerk link` | +| `Environment variables` | `clerk env pull` | +| `CLI version` | (no auto-fix; run `clerk update`) | +| `Shell completion` | (no auto-fix; see `clerk completion --help`) | + +All three remediation commands are themselves interactive by default: `auth login` opens a browser, `link` prompts for an app when `--app` is omitted, and `env pull` writes a file. In agent mode, prefer `clerk link --app ` over bare `clerk link`, since the bare form only works when silent autolink can resolve the target app without a picker. + +## What NOT to do in agent mode + +- **Don't ignore the sandbox warning.** If the CLI says host-only Clerk state or system capabilities may be unavailable, rerun the same command on the host before trusting the result. +- **Don't assume `clerk auth login` is fully unattended from an agent** - it opens a browser and waits for a callback. Prefer `CLERK_PLATFORM_API_KEY` for headless automation. `clerk init --app ` or init in an already linked project may still invoke the normal login fallback when a real app target is explicit. +- **Don't call `clerk link` without `--app` and assume the agent can pick for you** - it only succeeds when silent autolink can determine the app from detected keys. +- **Don't run `clerk unlink` in agent mode without `--yes`** - it exits with a usage error instead of prompting. +- **Don't run `clerk config put` without `--dry-run` first** - it's a full replacement and is destructive. +- **Don't skip `--yes` on mutations and expect them to work** - agent mode disables prompts, so commands that require confirmation will error. +- **Don't leak secret keys into logs** - the CLI never prints the raw secret key, and you shouldn't either. diff --git a/.agents/skills/clerk-cli/references/auth.md b/.agents/skills/clerk-cli/references/auth.md new file mode 100644 index 0000000..e77ed7c --- /dev/null +++ b/.agents/skills/clerk-cli/references/auth.md @@ -0,0 +1,155 @@ +# Clerk CLI - Authentication & Targeting Reference + +Everything you need to know about how the CLI authenticates, resolves keys, and targets the right application/instance. + +## Two APIs, two auth paths + +Clerk exposes two HTTP APIs. The CLI speaks both. + +| API | Base URL | Auth | Used for | CLI flag | +| ------------------------ | --------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------ | +| **Backend API (BAPI)** | `https://api.clerk.dev/v1/` | Instance **secret key** (`sk_...`) | Tenant data: users, orgs, sessions, invitations, JWT templates, webhooks. | (default) | +| **Platform API (PLAPI)** | `https://api.clerk.com/v1/` | **Platform API key** (`ak_...`) or OAuth token from `clerk auth login` | Account-level: listing your applications, fetching app/instance metadata, pulling config, billing. | `--platform` | + +You override the base URLs via `CLERK_BACKEND_API_URL` and `CLERK_PLATFORM_API_URL` when testing against non-production Clerk environments. + +### Backend API secret key resolution order + +When you run `clerk api /users` (no `--platform`), the CLI picks the `sk_` key in this order: + +1. `--secret-key ` flag (explicit override) +2. `CLERK_SECRET_KEY` environment variable +3. Auto-resolved from `--app ` (uses `CLERK_PLATFORM_API_KEY` or stored OAuth token to fetch the app's secret key) +4. Auto-resolved from the linked project profile (same mechanism as #3, but the app ID comes from the repo's link) + +The CLI validates prefixes: passing `ak_...` where `sk_...` is expected (or vice versa) throws an error immediately with guidance on which key type to use. + +### Platform API auth resolution order + +When you run `clerk api --platform ...`, or any command that already uses PLAPI (`apps list`, `config pull`, `link`, etc.), the CLI picks the bearer token in this order: + +1. `CLERK_PLATFORM_API_KEY` environment variable +2. Stored OAuth token from `clerk auth login` +3. If neither is present, the CLI errors: "Not authenticated. Run `clerk auth login` or set `CLERK_PLATFORM_API_KEY`." + +Set `CLERK_PLATFORM_API_KEY` for CI and scripted agent usage. Use `clerk auth login` for local interactive development. + +## Host vs sandbox behavior + +These auth and targeting rules only produce trustworthy results when the CLI +can actually reach the user's host state. + +In agent mode, the CLI now emits a best-effort warning once per invocation +when it detects that host-only Clerk state or system capabilities are +unavailable: + +```text +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. +``` + +That warning usually means one of the following is blocked: + +- Clerk home-directory config or fallback credential files +- OS keychain access +- outbound Clerk network access +- browser launch or localhost OAuth callback setup + +When that warning appears, stop trusting the current invocation's auth or +targeting result. A sandboxed run can misreport: + +- `Not logged in` / `auth_required` +- `Not authenticated. Run clerk auth login or set CLERK_PLATFORM_API_KEY` +- `No Clerk project linked` +- missing env or missing linked profile state + +Rerun the same command on the host before acting on it. + +> **`config` commands do not accept `--secret-key`.** They target the Platform API and authenticate via the PLAPI chain above (`CLERK_PLATFORM_API_KEY` or the stored OAuth token). If you need to script `config pull/schema/patch/put` in CI, export `CLERK_PLATFORM_API_KEY`; a Backend API `sk_...` key will not work. + +## Project linking + +`clerk link` stores a mapping from your repo to a Clerk application in the CLI config file (run `clerk doctor --verbose` to see the resolved path; override with `CLERK_CONFIG_DIR`). The key is the normalized git remote URL (e.g., `github.com/org/repo`), which means the link is shared across all clones and worktrees of the same repo automatically. + +When you run a command without `--app`/`--instance`: + +1. The CLI resolves the current repo's profile (normalized git remote → git common dir → current working directory). +2. If linked, it uses the stored app ID and instance IDs. +3. If not linked, it errors with guidance to run `clerk link`. + +## `--app` and `--instance` targeting + +Most commands accept `--app ` and `--instance ` to override the linked profile: + +- `--app ` - Clerk application ID (starts with `app_`). Works from any directory; no link required. +- `--instance ` - One of: + - `dev` (development instance, the default) + - `prod` (production instance) + - a full instance ID (starts with `ins_`) + +Examples: + +```sh +# Operate on a specific app without linking the repo +clerk api /users --app app_abc123 + +# Pull production env keys (dangerous - only when you know what you're doing) +clerk env pull --app app_abc123 --instance prod + +# Target a specific instance directly +clerk config pull --instance ins_2aB3c... +``` + +## Auth commands + +### `clerk auth login` + +Aliases: `signup`, `signin`, `sign-in`. Top-level shortcut: `clerk login`. + +OAuth 2.0 PKCE flow against the Clerk OAuth system instance (`https://clerk.clerk.com` by default, overridable via `CLERK_OAUTH_BASE_URL`): + +1. Generates PKCE parameters. +2. Starts a local callback server on `127.0.0.1`. +3. Opens the browser to `/oauth/authorize`. +4. Exchanges the code at `/oauth/token` for an access token. +5. Fetches user info from `/oauth/userinfo`. +6. Stores the token in the OS credential store. + +In agent mode, if already authenticated, it's a no-op. If not, it prints guidance rather than opening a browser. +In a sandbox, even the "already authenticated" check can be false if the +keychain or fallback credential file is blocked, so rerun on the host before +trusting a sandboxed auth failure. + +### `clerk auth logout` + +Aliases: `signout`, `sign-out`. Top-level shortcut: `clerk logout`. + +Clears the stored token. No API calls. + +### `clerk whoami` + +Hits `GET /oauth/userinfo` with the stored token and prints the email. Exits with a message if not logged in. + +## Environment variables the CLI honors + +| Variable | Effect | +| ------------------------ | --------------------------------------------------------------- | +| `CLERK_MODE` | Force `human` or `agent` mode (overrides TTY detection). | +| `CLERK_SECRET_KEY` | BAPI secret key (bypasses linked project / `--app` resolution). | +| `CLERK_PLATFORM_API_KEY` | PLAPI bearer key. | +| `CLERK_BACKEND_API_URL` | Override Backend API base URL. | +| `CLERK_PLATFORM_API_URL` | Override Platform API base URL. | +| `CLERK_OAUTH_BASE_URL` | Override OAuth base URL (advanced / internal). | +| `CLERK_CONFIG_DIR` | Override config, cache, and credential directory (advanced). | + +## Common auth failure modes + +| Symptom | Likely cause | Fix | +| ----------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------ | +| `Not authenticated` | No token stored, no `CLERK_PLATFORM_API_KEY` | `clerk auth login` or export `CLERK_PLATFORM_API_KEY` | +| `No Clerk project linked` | Running a command that needs a linked profile with no `--app` | `clerk link` or pass `--app ` | +| `Invalid secret key prefix` | Passed `ak_...` where `sk_...` expected (or vice versa) | Check which API the command hits; pass the matching key type | +| `Unauthorized` from API | Key belongs to a different instance | Verify `--instance` and ensure the key matches | +| Sandbox warning + auth/link failure | Host-only Clerk state or system capabilities are blocked | Rerun the same command on the host before trusting the error | + +When in doubt: `clerk doctor --json` walks through all of this and tells you exactly what's wrong. diff --git a/.agents/skills/clerk-cli/references/recipes.md b/.agents/skills/clerk-cli/references/recipes.md new file mode 100644 index 0000000..0ff4620 --- /dev/null +++ b/.agents/skills/clerk-cli/references/recipes.md @@ -0,0 +1,299 @@ +# Clerk CLI - Recipes + +Copy-pasteable patterns for common tasks. Treat these as starting points; confirm exact paths and parameters with `clerk api ls ` and `clerk --help`, since the Clerk API evolves. + +## Discovery first + +```sh +clerk api ls # everything Backend API exposes +clerk api ls users # filter by keyword +clerk api ls --platform # Platform API (account-level) +``` + +The bundled catalog is cached locally for 1 hour. There is no force-refresh flag - once the TTL expires the next `clerk api ls` re-fetches automatically; on fetch failure the CLI falls back to the stale cache and prints a warning. + +## Users + +```sh +# List users (preferred; curated flags). --limit defaults to 100 (max 250). +# JSON output is `{ data: [...], hasMore }` so callers can paginate without /users/count. +clerk users list +clerk users list --limit 50 --offset 0 --order-by -created_at + +# Count users (no curated subcommand; use the raw API) +clerk api /users/count + +# Fetch a user (no curated subcommand; use the raw API) +clerk api /users/user_abc123 + +# Search by email +clerk users list --email-address alice@example.com + +# Open a user's profile in the dashboard +clerk users open user_abc123 +clerk users open user_abc123 --print # print the URL instead of opening + +# Create a user (preferred; curated flags) +clerk users create \ + --email alice@example.com \ + --password 'SuperSecret123!' \ + --first-name Alice \ + --last-name Doe \ + --yes + +# Equivalent raw BAPI call. Use only when curated flags don't cover a field. +clerk api /users -d '{ + "email_address": ["alice@example.com"], + "password": "SuperSecret123!", + "first_name": "Alice", + "last_name": "Doe" +}' + +# Update (PATCH merges) +clerk api /users/user_abc123 -X PATCH -d '{"first_name":"Alicia"}' + +# Ban / unban +clerk api /users/user_abc123/ban -X POST +clerk api /users/user_abc123/unban -X POST + +# Lock / unlock +clerk api /users/user_abc123/lock -X POST +clerk api /users/user_abc123/unlock -X POST + +# Delete (PREVIEW FIRST) +clerk api /users/user_abc123 -X DELETE --dry-run +clerk api /users/user_abc123 -X DELETE --yes +``` + +### Test users (development only) + +For test accounts you need to sign into without real email or SMS delivery, Clerk provides two magic patterns that both verify with the fixed OTP `424242`. Use them on development instances; production rejects them. + +**By email.** Any address with the `+clerk_test` subaddress is recognized as a test email. The domain portion is arbitrary. + +```sh +# Create a test user with a test email (dev instance) +# `skip_password_checks` isn't a curated flag, so pass the body via `-d`. +clerk users create -d '{ + "email_address": ["demo+clerk_test@example.com"], + "password": "TestPass123!", + "skip_password_checks": true +}' --yes +``` + +**By phone.** Any US fictional phone number in the `+1 (XXX) 555-0100` through `+1 (XXX) 555-0199` range is recognized as a test phone. Pass the E.164 form. + +```sh +# Create a test user with a test phone (dev instance) +clerk users create -d '{ + "phone_number": ["+12015550100"], + "password": "TestPass123!", + "skip_password_checks": true +}' --yes +``` + +When signing in as either user in a browser or Playwright, enter `424242` at the OTP prompt. + +These patterns only apply to development instances. In production, client trust blocks sign-in regardless of suffix or number, and using real-looking test addresses is highly discouraged. Test addresses and numbers do not count against the dev-instance monthly caps (20 SMS, 100 emails). See [Clerk's test emails and phones reference](https://clerk.com/docs/guides/development/testing/test-emails-and-phones) for the full contract. + +## Organizations + +```sh +# List +clerk api /organizations +clerk api '/organizations?limit=20&query=acme' + +# Fetch +clerk api /organizations/org_abc123 + +# Create +clerk api /organizations -d '{"name":"Acme","created_by":"user_abc123"}' + +# Update +clerk api /organizations/org_abc123 -X PATCH -d '{"name":"Acme Inc."}' + +# Members +clerk api /organizations/org_abc123/memberships +clerk api /organizations/org_abc123/memberships -d '{"user_id":"user_xyz","role":"org:member"}' +clerk api /organizations/org_abc123/memberships/user_xyz -X PATCH -d '{"role":"org:admin"}' +clerk api /organizations/org_abc123/memberships/user_xyz -X DELETE --dry-run + +# Invitations +clerk api /organizations/org_abc123/invitations -d '{"email_address":"new@acme.com","role":"org:member"}' +``` + +If organization endpoints return `organization_not_enabled_in_instance`, enable the feature first: + +```sh +# Inspect org settings +clerk api /instance/organization_settings + +# Preview, then enable organizations for this instance +clerk api /instance/organization_settings -X PATCH -d '{"enabled":true}' --dry-run +clerk api /instance/organization_settings -X PATCH -d '{"enabled":true}' --yes +``` + +## Sessions + +```sh +# List active sessions for a user +clerk api '/sessions?user_id=user_abc123&status=active' + +# Revoke a session +clerk api /sessions/sess_abc123/revoke -X POST + +# Create an impersonation / sign-in token (for testing) +clerk api /sign_in_tokens -d '{"user_id":"user_abc123"}' +``` + +## Invitations (top-level, not org-scoped) + +```sh +clerk api /invitations +clerk api /invitations -d '{"email_address":"new@example.com","redirect_url":"https://example.com/welcome"}' +clerk api /invitations/inv_abc123/revoke -X POST +``` + +## JWT templates + +```sh +clerk api /jwt_templates +clerk api /jwt_templates/jtmp_abc123 +clerk api /jwt_templates -d '{ + "name": "supabase", + "claims": {"aud": "authenticated", "role": "authenticated"}, + "lifetime": 60 +}' +``` + +## Instance configuration + +Prefer the dedicated `config` commands over raw `api` calls - they handle confirmation, dry-run, and formatting. + +```sh +# Pull the current dev config +clerk config pull +clerk config pull --output config.dev.json + +# Pull production +clerk config pull --instance prod --output config.prod.json + +# Look at the schema to know what's available +clerk config schema --keys session sign_in social + +# PATCH: surgical updates +clerk config patch --json '{"session":{"lifetime":3600}}' --dry-run +clerk config patch --json '{"session":{"lifetime":3600}}' --yes + +# PUT: replace everything (destructive - always --dry-run first) +clerk config put --file config.prod.json --dry-run +clerk config put --file config.prod.json --instance prod --yes +``` + +## Environment variables + +```sh +# Pull dev keys into .env.local (auto-detects framework and key names) +clerk env pull + +# Pull production keys +clerk env pull --instance prod + +# Target a specific file +clerk env pull --file .env +``` + +`env pull` merges into the existing file: existing Clerk keys are updated in place; new ones are appended under a `# Clerk` header; everything else is preserved. + +## Applications (Platform API) + +```sh +# List your apps +clerk apps list +clerk apps list --json + +# Fetch one (raw API) +clerk api /v1/platform/applications/app_abc123 --platform +``` + +## Scripting patterns + +### Save large responses to a file before reading them + +`users list`, `apps list`, `config pull`, and most `clerk api` GETs can return responses ranging from kilobytes to megabytes. Reading the full payload into an LLM-driven session burns context for no benefit. Persist the response, then query just the slice you need: + +```sh +# Persist once, query as many times as you need. +clerk users list --json --limit 250 > /tmp/users.json + +jq '.data | length' /tmp/users.json # count rows on the page +jq '.hasMore' /tmp/users.json # any more pages? +jq '.data[0] | keys' /tmp/users.json # learn the shape of one record +jq '.data[] | {id, email_addresses}' /tmp/users.json # project to relevant fields only +``` + +If `jq` is not on `PATH`, fall back to Python or Node, which most environments have: + +```sh +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)' +``` + +Only `cat`/`head` the file when you genuinely need the raw structure for one-off debugging. + +### Pipe to `jq` + +For small responses (or one-shot lookups), inline piping to `jq` is fine: + +```sh +# Get a list of user IDs from the current page (the page envelope is `{ data, hasMore }`) +clerk users list --json | jq -r '.data[] | .id' + +# Count banned users on the current page +clerk users list --json | jq '[.data[] | select(.banned)] | length' + +# Walk every page until hasMore is false. Save each page to its own file so you +# can inspect them independently without re-fetching. +offset=0 +while :; do + page="/tmp/users-${offset}.json" + clerk users list --json --limit 250 --offset "$offset" > "$page" + jq -r '.data[] | .id' "$page" + [ "$(jq -r '.hasMore' "$page")" = "true" ] || break + offset=$((offset + 250)) +done +``` + +### Read body from stdin + +```sh +echo '{"first_name":"Bob"}' | clerk api /users/user_abc123 -X PATCH +jq -n '{email_address:["c@d.co"]}' | clerk api /users +``` + +### Loop safely + +```sh +# Always --dry-run first across the whole set. `users list` paginates; +# bump --limit (max 250) and walk pages with --offset until .hasMore is false. +for id in $(clerk users list --json --limit 250 | jq -r '.data[] | .id'); do + clerk api /users/$id -X PATCH -d '{"public_metadata":{"migrated":true}}' --dry-run +done +# Re-run without --dry-run once the previews look right +``` + +### Target multiple instances + +```sh +# Copy config from dev to staging for review +clerk config pull --instance dev --output /tmp/dev-config.json +clerk config patch --instance ins_staging --file /tmp/dev-config.json --dry-run +``` + +## When in doubt + +```sh +clerk api ls # find the right endpoint +clerk --help # authoritative flag list +clerk doctor --json # health check +``` diff --git a/.agents/skills/clerk-custom-ui/SKILL.md b/.agents/skills/clerk-custom-ui/SKILL.md new file mode 100644 index 0000000..e6e05dc --- /dev/null +++ b/.agents/skills/clerk-custom-ui/SKILL.md @@ -0,0 +1,175 @@ +--- +name: clerk-custom-ui +description: Custom authentication flows and component appearance - hooks (useSignIn, + useSignUp), themes, colors, fonts, CSS. Use for custom sign-in/sign-up flows, appearance + styling, visual customization, branding. +allowed-tools: WebFetch +license: MIT +metadata: + author: clerk + version: 2.3.0 +--- + +# Custom UI + +> **Prerequisite**: Ensure `ClerkProvider` wraps your app. See `clerk-setup` skill. +> +> **Version**: Check `package.json` for the SDK version — see `clerk` skill for the version table. This determines which custom flow references to use below. + +This skill covers two areas: +1. **Custom authentication flows** — build your own sign-in/sign-up UI with hooks +2. **Appearance customization** — theme, style, and brand Clerk's pre-built components + +## What Do You Need? + +| Task | Reference | +|------|-----------| +| Custom sign-in (Core 2 / LTS) | core-2/custom-sign-in.md | +| Custom sign-up (Core 2 / LTS) | core-2/custom-sign-up.md | +| Custom sign-in (Current SDK v7+) | core-3/custom-sign-in.md | +| Custom sign-up (Current SDK v7+) | core-3/custom-sign-up.md | +| Show component pattern (Current SDK) | core-3/show-component.md | + +## Custom Flow References + +| Task | Core 2 | Current | +|------|--------|---------| +| Custom sign-in (useSignIn) | `core-2/custom-sign-in.md` | `core-3/custom-sign-in.md` | +| Custom sign-up (useSignUp) | `core-2/custom-sign-up.md` | `core-3/custom-sign-up.md` | +| `` component | *(use ``, ``, ``)* | `core-3/show-component.md` | + +--- + +## Appearance Customization + +Appearance customization applies to both Core 2 and the current SDK. + +### Component Customization Options + +| Task | Documentation | +|------|---------------| +| Appearance prop overview | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/overview | +| Options (structure, logo, buttons) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/layout | +| Themes (pre-built dark/light) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/themes | +| Variables (colors, fonts, spacing) | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/variables | +| CAPTCHA configuration | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/captcha | +| Bring your own CSS | https://clerk.com/docs/nextjs/guides/customizing-clerk/appearance-prop/bring-your-own-css | + +### Appearance Pattern + +```typescript + +``` + +> **Core 2 ONLY (skip if current SDK):** The `options` property was named `layout`. Use `layout: { logoImageUrl: '...', socialButtonsVariant: '...' }` instead of `options`. + +### variables (colors, typography, borders) + +| Property | Description | +|----------|-------------| +| `colorPrimary` | Primary color throughout | +| `colorBackground` | Background color | +| `borderRadius` | Border radius (default: `0.375rem`) | + +**Opacity change:** `colorRing` and `colorModalBackdrop` now render at full opacity. Use explicit `rgba()` values if you need transparency. + +> **Core 2 ONLY (skip if current SDK):** `colorRing` and `colorModalBackdrop` rendered at 15% opacity by default. + +### options (structure, logo, social buttons) + +| Property | Description | +|----------|-------------| +| `logoImageUrl` | URL to custom logo | +| `socialButtonsVariant` | `'blockButton'` \| `'iconButton'` \| `'auto'` | +| `socialButtonsPlacement` | `'top'` \| `'bottom'` | +| `showOptionalFields` | Show optional fields (default: `false`) | + +> **Core 2 ONLY (skip if current SDK):** This property is called `layout`, not `options`. Also, `showOptionalFields` defaulted to `true`. + +### Themes + +Install themes from `@clerk/ui`: + +```bash +npm install @clerk/ui +``` + +```typescript +import { dark } from '@clerk/ui/themes' + + +``` + +> **Core 2 ONLY (skip if current SDK):** Themes are imported from `@clerk/themes` (install `@clerk/themes` instead of `@clerk/ui`). Example: `import { dark } from '@clerk/themes'`. + +**Theme stacking** — pass an array where the last theme takes precedence: + +```typescript +import { dark, neobrutalism } from '@clerk/ui/themes' + + +``` + +**CSS `color-scheme` support** — the default theme respects the CSS `color-scheme` property for automatic light/dark mode toggling. + +**Available themes:** `dark`, `neobrutalism`, `shadcn`, `simple` + +#### shadcn Theme + +> **IMPORTANT:** If the project has `components.json` (shadcn/ui installed), ALWAYS apply the shadcn theme as the FIRST customization step. This ensures Clerk components visually match the existing shadcn design system. Skip this only if the user explicitly requests a different theme. + +**If the project uses shadcn/ui** (check for `components.json` in the project root), **always use the shadcn theme**: + +```typescript +import { shadcn } from '@clerk/ui/themes' + + +``` + +Also import shadcn CSS in your global styles: +```css +@import 'tailwindcss'; +@import '@clerk/ui/themes/shadcn.css'; +``` + +> **Core 2 ONLY (skip if current SDK):** Import from `@clerk/themes` and `@clerk/themes/shadcn.css`: +> ```typescript +> import { shadcn } from '@clerk/themes' +> ``` +> ```css +> @import '@clerk/themes/shadcn.css'; +> ``` + +## Workflow + +1. Identify customization needs (custom flow or appearance) +2. For custom flows: check SDK version → read appropriate `core-2/` or `core-3/` reference +3. For appearance: WebFetch the appropriate documentation from table above +4. Apply appearance prop to your Clerk components or build custom flow with hooks + +## Common Pitfalls + +| Issue | Solution | +|-------|----------| +| Colors not applying | Use `colorPrimary` not `primaryColor` | +| Logo not showing | Put `logoImageUrl` inside `options: {}` (or `layout: {}` in Core 2) | +| Social buttons wrong | Add `socialButtonsVariant: 'iconButton'` in `options` (or `layout` in Core 2) | +| Styling not working | Use appearance prop, not direct CSS (unless with bring-your-own-css) | +| Hook returns different shape | Check SDK version — Core 2 and current have completely different `useSignIn`/`useSignUp` APIs | + +## See Also + +- `clerk-setup` - Initial Clerk install +- `clerk-nextjs-patterns` - Next.js patterns +- `clerk-orgs` - B2B organizations diff --git a/.agents/skills/clerk-custom-ui/core-2/custom-sign-in.md b/.agents/skills/clerk-custom-ui/core-2/custom-sign-in.md new file mode 100644 index 0000000..28759de --- /dev/null +++ b/.agents/skills/clerk-custom-ui/core-2/custom-sign-in.md @@ -0,0 +1,224 @@ +# Custom Sign-In Flow (Core 2) + +> This document covers the **older SDK** (`@clerk/nextjs` v5–v6, `@clerk/clerk-react` v5–v6, `@clerk/clerk-expo` v1–v2). For the current SDK, see `core-3/custom-sign-in.md`. + +Build a custom sign-in experience using the `useSignIn()` hook. + +## Hook API + +```typescript +import { useSignIn } from '@clerk/nextjs' // or @clerk/clerk-react, @clerk/clerk-expo + +const { signIn, isLoaded, setActive } = useSignIn() +``` + +| Property | Type | Description | +|----------|------|-------------| +| `signIn` | `SignIn` | Sign-in object with methods | +| `isLoaded` | `boolean` | Whether the hook has loaded | +| `setActive` | `(params) => Promise` | Sets the active session | + +## Sign-In Flow + +### 1. Create Sign-In + +```typescript +const result = await signIn.create({ + identifier: 'user@example.com', + password: 'securePassword123', +}) +``` + +### 2. First Factor Verification + +If additional verification is needed (email code, phone code): + +```typescript +// Prepare first factor +await signIn.prepareFirstFactor({ + strategy: 'email_code', // or 'phone_code' +}) + +// Attempt first factor +const result = await signIn.attemptFirstFactor({ + strategy: 'email_code', + code: '123456', +}) +``` + +### 3. Second Factor (MFA) + +If the sign-in requires MFA: + +```typescript +// Prepare second factor +await signIn.prepareSecondFactor({ + strategy: 'email_code', // or 'phone_code' +}) + +// Attempt second factor +const result = await signIn.attemptSecondFactor({ + strategy: 'totp', // or 'email_code', 'phone_code', 'backup_code' + code: '123456', +}) +``` + +### 4. Finalize + +Set the active session after successful authentication: + +```typescript +await setActive({ session: signIn.createdSessionId }) +``` + +### Password Reset + +```typescript +// 1. Start reset flow +await signIn.create({ strategy: 'reset_password_email_code', identifier: 'user@example.com' }) + +// or prepare after initial create: +await signIn.prepareFirstFactor({ strategy: 'reset_password_email_code' }) + +// 2. Verify reset code +await signIn.attemptFirstFactor({ strategy: 'reset_password_email_code', code: '123456' }) + +// 3. Set new password +await signIn.resetPassword({ password: 'newSecurePassword123' }) +``` + +### SSO (OAuth) + +```typescript +await signIn.authenticateWithRedirect({ + strategy: 'oauth_google', // or 'oauth_github', etc. + redirectUrl: '/sso-callback', + redirectUrlComplete: '/', +}) +``` + +## Error Handling + +Use try/catch with `isClerkAPIResponseError()`: + +```typescript +import { isClerkAPIResponseError } from '@clerk/nextjs/errors' + +try { + await signIn.create({ identifier, password }) +} catch (err) { + if (isClerkAPIResponseError(err)) { + err.errors.forEach((e) => { + console.log(e.code) // e.g. 'form_identifier_not_found' + console.log(e.message) // Human-readable message + console.log(e.longMessage) // Detailed message + }) + } +} +``` + +## Complete Example: Email/Password with MFA + +```tsx +'use client' +import { useState } from 'react' +import { useSignIn } from '@clerk/nextjs' +import { isClerkAPIResponseError } from '@clerk/nextjs/errors' +import { useRouter } from 'next/navigation' + +export default function SignInPage() { + const { signIn, isLoaded, setActive } = useSignIn() + const router = useRouter() + + const [identifier, setIdentifier] = useState('') + const [password, setPassword] = useState('') + const [mfaCode, setMfaCode] = useState('') + const [step, setStep] = useState<'credentials' | 'mfa'>('credentials') + const [error, setError] = useState('') + + if (!isLoaded) return
Loading...
+ + async function handleSignIn(e: React.FormEvent) { + e.preventDefault() + setError('') + + try { + const result = await signIn.create({ identifier, password }) + + if (result.status === 'needs_second_factor') { + setStep('mfa') + return + } + + if (result.status === 'complete') { + await setActive({ session: result.createdSessionId }) + router.push('/') + } + } catch (err) { + if (isClerkAPIResponseError(err)) { + setError(err.errors[0]?.message || 'Sign in failed') + } + } + } + + async function handleMFA(e: React.FormEvent) { + e.preventDefault() + setError('') + + try { + const result = await signIn.attemptSecondFactor({ + strategy: 'totp', + code: mfaCode, + }) + + if (result.status === 'complete') { + await setActive({ session: result.createdSessionId }) + router.push('/') + } + } catch (err) { + if (isClerkAPIResponseError(err)) { + setError(err.errors[0]?.message || 'Verification failed') + } + } + } + + if (step === 'mfa') { + return ( +
+ setMfaCode(e.target.value)} + placeholder="Enter MFA code" + /> + {error &&

{error}

} + +
+ ) + } + + return ( +
+ setIdentifier(e.target.value)} + placeholder="Email" + /> + setPassword(e.target.value)} + placeholder="Password" + /> + {error &&

{error}

} + +
+ ) +} +``` + +## Docs + +- [Custom sign-in flow](https://clerk.com/docs/custom-flows/overview) +- [useSignIn() reference](https://clerk.com/docs/references/react/use-sign-in) diff --git a/.agents/skills/clerk-custom-ui/core-2/custom-sign-up.md b/.agents/skills/clerk-custom-ui/core-2/custom-sign-up.md new file mode 100644 index 0000000..574dbe7 --- /dev/null +++ b/.agents/skills/clerk-custom-ui/core-2/custom-sign-up.md @@ -0,0 +1,190 @@ +# Custom Sign-Up Flow (Core 2) + +> This document covers the **older SDK** (`@clerk/nextjs` v5–v6, `@clerk/clerk-react` v5–v6, `@clerk/clerk-expo` v1–v2). For the current SDK, see `core-3/custom-sign-up.md`. + +Build a custom sign-up experience using the `useSignUp()` hook. + +## Hook API + +```typescript +import { useSignUp } from '@clerk/nextjs' // or @clerk/clerk-react, @clerk/clerk-expo + +const { signUp, isLoaded, setActive } = useSignUp() +``` + +| Property | Type | Description | +|----------|------|-------------| +| `signUp` | `SignUp` | Sign-up object with methods | +| `isLoaded` | `boolean` | Whether the hook has loaded | +| `setActive` | `(params) => Promise` | Sets the active session | + +## Sign-Up Flow + +### 1. Create Sign-Up + +```typescript +const result = await signUp.create({ + emailAddress: 'user@example.com', + password: 'securePassword123', + firstName: 'Jane', // optional + lastName: 'Doe', // optional +}) +``` + +### 2. Prepare Verification + +Send a verification code to the user's email or phone: + +```typescript +await signUp.prepareVerification({ + strategy: 'email_code', // or 'phone_code', 'email_link' +}) +``` + +### 3. Attempt Verification + +Verify the code the user received: + +```typescript +const result = await signUp.attemptVerification({ + strategy: 'email_code', + code: '123456', +}) +``` + +### 4. Finalize + +Set the active session after successful sign-up: + +```typescript +await setActive({ session: signUp.createdSessionId }) +``` + +### SSO (OAuth) + +```typescript +await signUp.authenticateWithRedirect({ + strategy: 'oauth_google', + redirectUrl: '/sso-callback', + redirectUrlComplete: '/', +}) +``` + +## Error Handling + +Use try/catch with `isClerkAPIResponseError()`: + +```typescript +import { isClerkAPIResponseError } from '@clerk/nextjs/errors' + +try { + await signUp.create({ emailAddress, password }) +} catch (err) { + if (isClerkAPIResponseError(err)) { + err.errors.forEach((e) => { + console.log(e.code) // e.g. 'form_password_pwned' + console.log(e.message) // Human-readable message + console.log(e.longMessage) // Detailed message + }) + } +} +``` + +## Complete Example: Email/Password with Email Verification + +```tsx +'use client' +import { useState } from 'react' +import { useSignUp } from '@clerk/nextjs' +import { isClerkAPIResponseError } from '@clerk/nextjs/errors' +import { useRouter } from 'next/navigation' + +export default function SignUpPage() { + const { signUp, isLoaded, setActive } = useSignUp() + const router = useRouter() + + const [email, setEmail] = useState('') + const [password, setPassword] = useState('') + const [code, setCode] = useState('') + const [step, setStep] = useState<'register' | 'verify'>('register') + const [error, setError] = useState('') + + if (!isLoaded) return
Loading...
+ + async function handleRegister(e: React.FormEvent) { + e.preventDefault() + setError('') + + try { + await signUp.create({ emailAddress: email, password }) + await signUp.prepareVerification({ strategy: 'email_code' }) + setStep('verify') + } catch (err) { + if (isClerkAPIResponseError(err)) { + setError(err.errors[0]?.message || 'Sign up failed') + } + } + } + + async function handleVerify(e: React.FormEvent) { + e.preventDefault() + setError('') + + try { + const result = await signUp.attemptVerification({ + strategy: 'email_code', + code, + }) + + if (result.status === 'complete') { + await setActive({ session: result.createdSessionId }) + router.push('/') + } + } catch (err) { + if (isClerkAPIResponseError(err)) { + setError(err.errors[0]?.message || 'Verification failed') + } + } + } + + if (step === 'verify') { + return ( +
+

Check your email for a verification code.

+ setCode(e.target.value)} + placeholder="Verification code" + /> + {error &&

{error}

} + +
+ ) + } + + return ( +
+ setEmail(e.target.value)} + placeholder="Email" + /> + setPassword(e.target.value)} + placeholder="Password" + /> + {error &&

{error}

} + +
+ ) +} +``` + +## Docs + +- [Custom sign-up flow](https://clerk.com/docs/custom-flows/overview) +- [useSignUp() reference](https://clerk.com/docs/references/react/use-sign-up) diff --git a/.agents/skills/clerk-custom-ui/core-3/custom-sign-in.md b/.agents/skills/clerk-custom-ui/core-3/custom-sign-in.md new file mode 100644 index 0000000..50f13c2 --- /dev/null +++ b/.agents/skills/clerk-custom-ui/core-3/custom-sign-in.md @@ -0,0 +1,314 @@ +# Custom Sign-In Flow + +Build a custom sign-in experience using the `useSignIn()` hook. + +## Hook API + +```typescript +import { useSignIn } from '@clerk/nextjs' // or @clerk/react, @clerk/expo + +const { signIn, errors, fetchStatus } = useSignIn() +``` + +| Property | Type | Description | +|----------|------|-------------| +| `signIn` | `SignInFuture` | Sign-in object with namespaced methods | +| `errors` | `Errors` | Structured error object | +| `fetchStatus` | `'idle' \| 'fetching'` | Network request status | + +## Sign-In Methods + +### Password + +```typescript +const { error } = await signIn.password({ + identifier: 'user@example.com', + password: 'securePassword123', +}) +``` + +### SSO (OAuth / Enterprise) + +```typescript +const { error } = await signIn.sso({ + strategy: 'oauth_google', // or 'oauth_github', 'enterprise_sso', etc. + redirectUrl: '/dashboard', // where to go after SSO completes + redirectCallbackUrl: '/sso-callback', // intermediate callback route +}) +``` + +### Passkey + +```typescript +const { error } = await signIn.passkey({ flow: 'discoverable' }) +``` + +### Web3 + +```typescript +const { error } = await signIn.web3({ strategy: 'web3_solana_signature' }) +// or +const { error } = await signIn.web3({ strategy: 'web3_base_signature' }) +``` + +### Ticket (Invitation link) + +```typescript +const { error } = await signIn.ticket({ ticket: 'ticket_abc123' }) +``` + +### Email Code + +```typescript +// Send code (emailAddress is optional if a signIn already exists from a prior method call) +const { error } = await signIn.emailCode.sendCode({ emailAddress: 'user@example.com' }) + +// Verify code +const { error } = await signIn.emailCode.verifyCode({ code: '123456' }) +``` + +### Phone Code + +```typescript +// Send code (phoneNumber is optional if a signIn already exists from a prior method call) +const { error } = await signIn.phoneCode.sendCode({ phoneNumber: '+12015551234' }) + +// Verify code +const { error } = await signIn.phoneCode.verifyCode({ code: '123456' }) +``` + +## MFA (Second Factor) + +A second factor is required when `signIn.status` is one of: +- `'needs_second_factor'` — user has MFA enabled (TOTP, backup codes, etc.) +- `'needs_client_trust'` — new device sign-in without MFA; requires email or phone code verification + +```typescript +// TOTP (Authenticator app) +const { error } = await signIn.mfa.verifyTOTP({ code: '123456' }) + +// Backup code +const { error } = await signIn.mfa.verifyBackupCode({ code: 'backup-code-here' }) + +// Email code +const { error: sendErr } = await signIn.mfa.sendEmailCode() +const { error: verifyErr } = await signIn.mfa.verifyEmailCode({ code: '123456' }) + +// Phone code +const { error: sendErr } = await signIn.mfa.sendPhoneCode() +const { error: verifyErr } = await signIn.mfa.verifyPhoneCode({ code: '123456' }) +``` + +## Password Reset + +```typescript +// 1. Send reset code +const { error } = await signIn.resetPasswordEmailCode.sendCode() + +// 2. Verify the code +const { error } = await signIn.resetPasswordEmailCode.verifyCode({ code: '123456' }) + +// 3. Submit new password +const { error } = await signIn.resetPasswordEmailCode.submitPassword({ + password: 'newSecurePassword123', +}) +``` + +## Client Trust + +When a user signs in with a valid password from a new device without MFA enabled, the sign-in status becomes `needs_client_trust`. This requires an additional verification step: + +```typescript +if (signIn.status === 'needs_client_trust') { + // Check supportedSecondFactors for available methods (email_code or phone_code) + const factors = signIn.supportedSecondFactors + // Use the appropriate mfa method to verify +} +``` + +## Finalizing Sign-In + +After successful authentication, call `finalize()` to activate the session: + +```typescript +await signIn.finalize({ + navigate: async ({ session, decorateUrl }) => { + const destination = session.currentTask + ? `/sign-in/tasks/${session.currentTask.key}` + : '/' + const url = decorateUrl(destination) + // decorateUrl may return an absolute URL for Safari ITP + if (url.startsWith('http')) { + window.location.href = url + } else { + router.push(url) + } + }, +}) +``` + +- `decorateUrl(path)` — decorates the URL with session info (required to support Safari's Intelligent Tracking Prevention). May return an absolute URL. +- `session.currentTask` — check for pending session tasks before redirecting + +### Reset State + +Clear local sign-in state and start over: + +```typescript +signIn.reset() +``` + +## Error Handling + +All methods return `Promise<{ error: ClerkError | null }>`. Errors are also available reactively on the hook: + +```typescript +const { signIn, errors } = useSignIn() + +// Field-level errors +errors?.fields?.identifier // { code, message, longMessage? } +errors?.fields?.password // { code, message, longMessage? } +errors?.fields?.code // { code, message, longMessage? } + +// Global errors (not tied to a field) +errors?.global // ClerkGlobalHookError[] | null + +// Raw error array +errors?.raw // ClerkError[] | null +``` + +## Complete Example: Email/Password with MFA + +From [the docs](https://clerk.com/docs/guides/development/custom-flows/authentication/multi-factor-authentication). Supports SMS verification codes, authenticator app (TOTP), and backup codes. + +```tsx +'use client' + +import { useSignIn } from '@clerk/nextjs' +import { useRouter } from 'next/navigation' + +export default function Page() { + const { signIn, errors, fetchStatus } = useSignIn() + const router = useRouter() + + const handleSubmit = async (formData: FormData) => { + const emailAddress = formData.get('email') as string + const password = formData.get('password') as string + + await signIn.password({ + emailAddress, + password, + }) + + // If you're using the authenticator app strategy, remove this check. + if (signIn.status === 'needs_second_factor') { + await signIn.mfa.sendPhoneCode() + } + + if (signIn.status === 'complete') { + await signIn.finalize({ + navigate: ({ session, decorateUrl }) => { + if (session?.currentTask) { + // Handle pending session tasks + // See https://clerk.com/docs/guides/development/custom-flows/authentication/session-tasks + console.log(session?.currentTask) + return + } + + const url = decorateUrl('/') + if (url.startsWith('http')) { + window.location.href = url + } else { + router.push(url) + } + }, + }) + } + } + + const handleMFAVerification = async (formData: FormData) => { + const code = formData.get('code') as string + const useBackupCode = formData.get('useBackupCode') === 'on' + + if (useBackupCode) { + await signIn.mfa.verifyBackupCode({ code }) + } else { + await signIn.mfa.verifyPhoneCode({ code }) + // If you're using the authenticator app strategy, use the following method instead: + // await signIn.mfa.verifyTOTP({ code }) + } + + if (signIn.status === 'complete') { + await signIn.finalize({ + navigate: ({ session, decorateUrl }) => { + if (session?.currentTask) { + // Handle pending session tasks + // See https://clerk.com/docs/guides/development/custom-flows/authentication/session-tasks + console.log(session?.currentTask) + return + } + + const url = decorateUrl('/') + if (url.startsWith('http')) { + window.location.href = url + } else { + router.push(url) + } + }, + }) + } + } + + if (signIn.status === 'needs_second_factor') { + return ( +
+

Verify your account

+
+
+ + + {errors.fields.code &&

{errors.fields.code.message}

} +
+
+ +
+ +
+
+ ) + } + + return ( + <> +

Sign in

+
+
+ + + {errors.fields.identifier &&

{errors.fields.identifier.message}

} +
+
+ + + {errors.fields.password &&

{errors.fields.password.message}

} +
+ +
+ {errors &&

{JSON.stringify(errors, null, 2)}

} + + ) +} +``` + +## Docs + +- [Custom sign-in flow](https://clerk.com/docs/custom-flows/overview) +- [MFA custom flow](https://clerk.com/docs/guides/development/custom-flows/authentication/multi-factor-authentication) +- [useSignIn() reference](https://clerk.com/docs/references/react/use-sign-in) diff --git a/.agents/skills/clerk-custom-ui/core-3/custom-sign-up.md b/.agents/skills/clerk-custom-ui/core-3/custom-sign-up.md new file mode 100644 index 0000000..ac243ba --- /dev/null +++ b/.agents/skills/clerk-custom-ui/core-3/custom-sign-up.md @@ -0,0 +1,259 @@ +# Custom Sign-Up Flow + +Build a custom sign-up experience using the `useSignUp()` hook. + +## Hook API + +```typescript +import { useSignUp } from '@clerk/nextjs' // or @clerk/react, @clerk/expo + +const { signUp, errors, fetchStatus } = useSignUp() +``` + +| Property | Type | Description | +|----------|------|-------------| +| `signUp` | `SignUpFuture` | Sign-up object with namespaced methods | +| `errors` | `Errors` | Structured error object | +| `fetchStatus` | `'idle' \| 'fetching'` | Network request status | + +## Sign-Up Methods + +### Password (Email/Password) + +```typescript +const { error } = await signUp.password({ + emailAddress: 'user@example.com', + password: 'securePassword123', + firstName: 'Jane', // optional + lastName: 'Doe', // optional +}) +``` + +### SSO (OAuth) + +```typescript +const { error } = await signUp.sso({ + strategy: 'oauth_google', // or 'oauth_github', etc. + redirectUrl: '/dashboard', // where to go after SSO completes + redirectCallbackUrl: '/sso-callback', // intermediate callback route +}) +``` + +### Web3 + +```typescript +const { error } = await signUp.web3({ strategy: 'web3_solana_signature' }) +``` + +### Update (add fields to existing sign-up) + +Use `update()` to add optional fields (name, metadata, legal acceptance, locale) to an existing sign-up before finalization. + +```typescript +const { error } = await signUp.update({ + firstName: 'Jane', + lastName: 'Doe', + unsafeMetadata: { referralSource: 'twitter' }, + legalAccepted: true, +}) +``` + +## Email / Phone Verification + +After creating a sign-up, verify the user's email or phone: + +### Email Code + +```typescript +// Send verification code +const { error } = await signUp.verifications.sendEmailCode() + +// Verify the code +const { error } = await signUp.verifications.verifyEmailCode({ code: '123456' }) +``` + +### Phone Code + +```typescript +// Send verification code +const { error } = await signUp.verifications.sendPhoneCode() + +// Verify the code +const { error } = await signUp.verifications.verifyPhoneCode({ code: '123456' }) +``` + +### Email Link + +```typescript +// verificationUrl: where the user lands after clicking the email link (relative or absolute) +const { error } = await signUp.verifications.sendEmailLink({ verificationUrl: '/verify' }) +// User clicks the link in their email to verify +``` + +## Finalizing Sign-Up + +After successful sign-up and verification, call `finalize()` to activate the session: + +```typescript +await signUp.finalize({ + navigate: async ({ session, decorateUrl }) => { + const destination = session.currentTask + ? `/sign-up/tasks/${session.currentTask.key}` + : '/' + const url = decorateUrl(destination) + // decorateUrl may return an absolute URL for Safari ITP + if (url.startsWith('http')) { + window.location.href = url + } else { + router.push(url) + } + }, +}) +``` + +### Transferable Sign-Ups + +If `signUp.isTransferable` is `true`, the identifier matches an existing user and the sign-up should be transferred to a sign-in flow. This involves coordinating between sign-up and sign-in resources. See the [transferable sign-up docs](https://clerk.com/docs/custom-flows/overview) for the full implementation. + +### Reset State + +Clear local sign-up state and start over: + +```typescript +signUp.reset() +``` + +## Error Handling + +All methods return `Promise<{ error: ClerkError | null }>`. Errors are also available reactively on the hook: + +```typescript +const { signUp, errors } = useSignUp() + +// Field-level errors +errors?.fields?.emailAddress // { code, message, longMessage? } +errors?.fields?.password // { code, message, longMessage? } +errors?.fields?.firstName // { code, message, longMessage? } +errors?.fields?.lastName // { code, message, longMessage? } +errors?.fields?.phoneNumber // { code, message, longMessage? } +errors?.fields?.username // { code, message, longMessage? } +errors?.fields?.code // { code, message, longMessage? } + +// Global errors +errors?.global // ClerkGlobalHookError[] | null + +// Raw error array +errors?.raw // ClerkError[] | null +``` + +## Complete Example: Phone OTP Sign-Up + +From [the docs](https://clerk.com/docs/guides/development/custom-flows/authentication/email-sms-otp). Uses phone OTP with inline comments for adapting to email OTP. + +```tsx +'use client' + +import * as React from 'react' +import { useAuth, useSignUp } from '@clerk/nextjs' +import { useRouter } from 'next/navigation' + +export default function SignUpPage() { + const { signUp, errors, fetchStatus } = useSignUp() + const { isSignedIn } = useAuth() + const router = useRouter() + + const handleSubmit = async (formData: FormData) => { + // For email OTP: collect the email address instead of the phone number + const phoneNumber = formData.get('phoneNumber') as string + + // For email OTP: change create({ phoneNumber }) to create({ emailAddress }) + const error = await signUp.create({ phoneNumber }) + + // For email OTP: change sendPhoneCode() to sendEmailCode() + if (!error) await signUp.verifications.sendPhoneCode() + } + + const handleVerify = async (formData: FormData) => { + const code = formData.get('code') as string + + // For email OTP: change verifyPhoneCode() to verifyEmailCode() + await signUp.verifications.verifyPhoneCode({ code }) + + if (signUp.status === 'complete') { + await signUp.finalize({ + navigate: ({ session, decorateUrl }) => { + if (session?.currentTask) { + // Handle pending session tasks + // See https://clerk.com/docs/guides/development/custom-flows/authentication/session-tasks + console.log(session?.currentTask) + return + } + + const url = decorateUrl('/') + if (url.startsWith('http')) { + window.location.href = url + } else { + router.push(url) + } + }, + }) + } + } + + if (signUp.status === 'complete' || isSignedIn) { + return null + } + + if ( + signUp.status === 'missing_requirements' && + // For email OTP: check for phone_number instead of email_address + signUp.unverifiedFields.includes('phone_number') && + signUp.missingFields.length === 0 + ) { + return ( + <> +

Verify your account

+
+
+ + +
+ {errors.fields.code &&

{errors.fields.code.message}

} + +
+ {/* For email OTP: change sendPhoneCode() to sendEmailCode() */} + + + ) + } + + return ( + <> +

Sign up

+
+ {/* For email OTP: collect the emailAddress instead */} +
+ + + {errors.fields.phoneNumber &&

{errors.fields.phoneNumber.message}

} +
+ +
+ {errors &&

{JSON.stringify(errors, null, 2)}

} + + {/* Required for sign-up flows. Clerk's bot sign-up protection is enabled by default */} +
+ + ) +} +``` + +## Docs + +- [Custom sign-up flow](https://clerk.com/docs/custom-flows/overview) +- [Email/phone OTP custom flow](https://clerk.com/docs/guides/development/custom-flows/authentication/email-sms-otp) +- [useSignUp() reference](https://clerk.com/docs/references/react/use-sign-up) diff --git a/.agents/skills/clerk-custom-ui/core-3/show-component.md b/.agents/skills/clerk-custom-ui/core-3/show-component.md new file mode 100644 index 0000000..f01a8b4 --- /dev/null +++ b/.agents/skills/clerk-custom-ui/core-3/show-component.md @@ -0,0 +1,125 @@ +# `` Component + +The `` component conditionally renders content based on authentication state, roles, permissions, billing plans, and features. + +> **Core 2 ONLY (skip if current SDK):** The `` component does not exist in Core 2. Use ``, ``, and `` instead. See migration table below. + +## Import + +```typescript +import { Show } from '@clerk/nextjs' // Next.js +import { Show } from '@clerk/react' // React +import { Show } from '@clerk/react-router' // React Router +import { Show } from '@clerk/expo' // Expo +``` + +## Props + +| Prop | Type | Description | +|------|------|-------------| +| `when` | `string \| object \| function` | Condition for rendering children | +| `fallback?` | `ReactNode` | Content shown when condition fails | +| `treatPendingAsSignedOut?` | `boolean` | Treat pending sessions as signed-out (default: `true`) | + +## `when` Prop Variants + +### Authentication State + +```tsx +// Show content only when signed in + +

Welcome back!

+ + +// Show content only when signed out + +

Please sign in.

+ +``` + +### Role Check + +```tsx + + + +``` + +### Permission Check + +```tsx + + + +``` + +### Billing Feature Check + +```tsx + + + +``` + +### Billing Plan Check + +```tsx + + + +``` + +### Custom Condition (Function) + +```tsx + has({ role: 'org:admin' }) || has({ permission: 'org:billing:manage' })}> + + +``` + +## Fallback Content + +Show alternative content when the condition fails: + +```tsx +Please sign in to continue.

}> + + +``` + +## Session Tasks and Pending State + +The `treatPendingAsSignedOut` prop controls how pending sessions (sessions with incomplete tasks) are handled: + +```tsx +// Default: pending sessions are treated as signed-out + + + + +// Treat pending sessions as signed-in (e.g., to show task completion UI) + + + +``` + +## Security Caveat + +**`` only visually hides content** — it remains in browser source. It is not a security boundary. For protecting sensitive data, always verify authentication server-side with `auth()` or use `auth.protect()` in middleware. + +## Migration from Core 2 + +| Core 2 | Current | +|--------|---------| +| `` | `` | +| `` | `` | +| `` | `` | +| `` | `` | +| ` expr}>` | ` expr}>` | +| `` | `` | +| *(no equivalent)* | `` | +| *(no equivalent)* | `` | + +## Docs + +- [Show component reference](https://clerk.com/docs/components/control/show) diff --git a/.agents/skills/clerk-expo-patterns/SKILL.md b/.agents/skills/clerk-expo-patterns/SKILL.md new file mode 100644 index 0000000..8dab9e0 --- /dev/null +++ b/.agents/skills/clerk-expo-patterns/SKILL.md @@ -0,0 +1,169 @@ +--- +name: clerk-expo-patterns +description: 'Expo / React Native patterns with Clerk — SecureStore token cache, OAuth + deep linking, useAuth in native, Expo Router protected routes, push notifications + with user context. Triggers on: expo clerk, clerk react native, SecureStore token + cache, expo router auth, OAuth deep link clerk, mobile auth clerk.' +license: MIT +allowed-tools: WebFetch +metadata: + author: clerk + version: 1.0.0 +compatibility: Requires Expo CLI and expo-secure-store package +--- + +# Expo Patterns + +SDK: `@clerk/expo` v3+. Requires Expo 53+, React Native 0.73+. + +## What Do You Need? + +| Task | Reference | +|------|-----------| +| Persist tokens with SecureStore | references/token-storage.md | +| OAuth (Google, Apple, GitHub) | references/oauth-deep-linking.md | +| Protected screens with Expo Router | references/protected-routes.md | +| Push notifications with user data | references/push-notifications.md | + +## Mental Model + +Clerk stores the session token in memory by default. In native apps: + +- **SecureStore** — encrypt token in device keychain (recommended for production) +- **`tokenCache`** — prop on `` that provides custom storage +- **`useAuth`** — same API as web, works in any component +- **OAuth** — requires `useSSO` + deep link scheme configured in `app.json` + +## Minimal Setup + +### app/_layout.tsx + +```tsx +import { ClerkProvider } from '@clerk/expo' +import { tokenCache } from '@clerk/expo/token-cache' +import { Stack } from 'expo-router' + +const publishableKey = process.env.EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY! + +export default function RootLayout() { + return ( + + + + ) +} +``` + +> **CRITICAL**: Use `EXPO_PUBLIC_CLERK_PUBLISHABLE_KEY` — not `NEXT_PUBLIC_`. Env vars inside `node_modules` are not inlined in production builds. Always pass `publishableKey` explicitly. + +## Built-in Token Cache + +```tsx +import { tokenCache } from '@clerk/expo/token-cache' +``` + +This uses `expo-secure-store` with `keychainAccessible: AFTER_FIRST_UNLOCK`. Install the peer dep: + +```bash +npx expo install expo-secure-store +``` + +## Auth Hooks + +```tsx +import { useAuth, useUser, useSignIn, useSignUp, useClerk } from '@clerk/expo' + +export function ProfileScreen() { + const { isSignedIn, userId, signOut } = useAuth() + const { user } = useUser() + + if (!isSignedIn) return + return ( + + {user?.fullName} +