Clerk CLI은(는) 무엇을 하나요?
clerk 바이너리는 Clerk 백엔드 API 및 플랫폼 API에 사전 인증된 게이트웨이 역할을 하며, 프로젝트 수준 도구(인증, 연결, 환경 변수 가져오기, 인스턴스 설정)를 제공합니다. 사용자가 Clerk 리소스와 관련된 질문을 할 때는 직접 curl을 사용하는 대신 clerk를 먼저 사용하세요.
이 스킬은
clerk latest를 대상으로 합니다.clerk --version이 최신 CLI 버전과 일치하지 않으면clerk skill install또는bunx clerk@latest와 같은 패키지 러너로 업데이트하세요. 바이너리가 항상 최신 정보의 원천이므로, 이 스킬에서 주장하는 내용을 확인하려면clerk <command> --help를 실행하세요.
실행 환경 (호스트 선호, 샌드박스 경고 이해)
대부분의 AI 코딩 에이전트는 기본적으로 셸 명령어를 샌드박스에서 실행하며, 사용자의 홈 디렉토리, OS 키체인, 브라우저 실행, localhost 콜백 바인딩 또는 네트워크 접근이 차단될 수 있습니다. Clerk CLI는 이러한 모든 호스트 기능에 의존합니다.
- OS 자격 증명 저장소:
clerk auth login은 OAuth 토큰을 시스템 키체인에 저장합니다. 키체인 접근이 없는 샌드박스는 호스트가 인증되었더라도 "로그인되지 않음"을 보고합니다. - 홈 디렉토리 Clerk 상태: 저장된 구성, 캐시된 메타데이터, 대체 자격 증명은 사용자의 Clerk 구성/데이터 디렉토리 아래에 있습니다.
- 연결된 프로젝트 메타데이터: 저장소의 git 리모트와 Clerk 구성을 기반으로 확인합니다. 저장소 상태가 제거되거나 홈 디렉토리 읽기가 차단된 샌드박스는 "연결되지 않음"을 잘못 보고할 수 있습니다.
- 로컬
.env*파일:clerk env pull로 생성된 게시 가능 키와 비밀 키입니다. - Clerk에 대한 아웃바운드 네트워크 접근: 모든 백엔드 및 플랫폼 API 호출에 필요합니다.
- 브라우저 + localhost OAuth 콜백:
clerk auth login에 필요합니다.
에이전트 모드에서 CLI는 이제 호스트 민감 라이브러리 경계에서 최선의 노력으로 한 번 경고합니다. 호스트 전용 Clerk 상태 또는 시스템 기능을 사용할 수 없음을 감지하면 다음을 출력합니다.
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.
해당 경고를 신뢰하세요. 명령어는 계속 실행될 수 있지만, 해당 호출에서 발생하는 인증, 연결, 환경 변수, 구성, API, 브라우저 또는 OAuth 콜백 실패는 동일한 명령어를 호스트에서 다시 실행할 때까지 신뢰할 수 없습니다.
다음 명령어는 샌드박스가 아닌 사용자 호스트 셸에서 실행하는 것을 선호합니다:
clerk doctor, clerk whoami, clerk auth login, clerk link, clerk env pull,
clerk apps ..., clerk config ..., clerk api ....
명령어가 실수로 샌드박스에서 실행되어 Not logged in, auth_required, not linked, 환경 변수 누락, 키체인/파일 권한 오류 또는 네트워크 실패를 보고하는 경우, 결과를 신뢰할 수 있는 것으로 간주하지 마세요. 해당 결과에 대해 조치를 취하거나 사용자에게 보고하기 전에 호스트에서 다시 실행하세요.
CLI 호출
clerk 명령어를 실행하기 전에 호출할 바이너리를 결정하고 해당 선택을 세션 전체에 고정하세요.
# 1. 전역 설치된 바이너리가 스킬의 대상 버전과 일치하면 이를 선호합니다.
command -v clerk >/dev/null 2>&1 && clerk --version
latest 또는 신뢰할 수 있는 버전이 출력되면 나머지 세션 동안 clerk를 그대로 사용하세요.
그렇지 않으면 다음 순서로 패키지 러너를 사용하세요(CLI 자체의 preferredRunner 로직과 일치하며, 프로젝트의 lockfile과 일치하는 러너를 선호합니다).
| 프로젝트 패키지 매니저 | 호출 방법 |
|---|---|
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)에는 dlx가 없습니다. 이러한 프로젝트는 "선호 러너 없음"으로 처리하고 PATH에 있는 위 목록의 첫 번째 러너로 대체하세요.
게시된 npm 패키지는 **clerk**이며, @clerk/cli가 아닙니다. npm install -g clerk를 기본 경로로 가르치지 마세요. 전역 CLI가 오래되었거나 이 스킬과 다르게 동작하면 전역 설치를 업그레이드하거나 위의 latest 러너 형식으로 대체하세요.
사전 요구 사항 (세션 시작 시 실행)
세션에서 다른 Clerk 명령어를 실행하기 전에 CLI가 인증되고, 연결되었으며, 정상 상태인지 확인하세요.
clerk --version # 바이너리가 PATH에 있는지 확인
clerk doctor --json # 구조화된 상태 확인; 실패 시 exit 1
항상 clerk doctor --json을 먼저 실행하세요. 일반적인 설정 실패(로그인되지 않음, 프로젝트가 연결되지 않음, 키 누락, 오래된 CLI 버전)를 사전에 포착하여 이후 명령어가 혼란스러운 오류로 실패하는 것을 방지합니다. 에이전트 모드에서는 Clerk의 호스트 측 구성/자격 증명 디렉토리에 쓸 수 없는지 확인하는 Host execution 검사도 포함되며, 이는 현재 호출이 샌드박스 환경일 가능성이 높다는 표준 신호입니다.
각 결과에는 name, status (pass/warn/fail), message, 선택적 detail, 선택적 remedy (수정 방법), 선택적 fix (자동 수정 가능 문제 레이블)가 포함됩니다. 이를 파싱하여 조치를 취하거나 사용자에게 알리세요. Host execution이 경고하면 동일한 샌드박스 실행에서 발생한 인증/연결/환경 변수/API 실패를 신뢰하기 전에 호스트에서 명령어를 다시 실행하세요. 이후 명령어가 오작동하기 시작하면 clerk doctor --json을 다시 실행하세요.
clerk --version이 이 스킬이 다루는 것보다 최신 CLI를 보고하면 clerk <command> --help를 먼저 신뢰하고 이 스킬 번들을 소스에서 업데이트하세요.
개념 모델
| 계층 | 수행 작업 | 명령어 |
|---|---|---|
| 세션 / 프로젝트 | 인증, 저장소를 Clerk 앱에 연결, 환경 변수 키 가져오기 | auth login, link, unlink, whoami, env pull, doctor |
| 인스턴스 구성 | 특정 인스턴스에 대한 구성(소셜 제공자, 세션 수명 등) 관리 | config pull, config schema, config patch, config put |
| 백엔드 API (기본) | 런타임 데이터: 사용자, 조직, 세션, 초대, JWT 템플릿, 웹훅 | clerk api <path> |
플랫폼 API (--platform) | 계정 수준: 애플리케이션, 인스턴스, 청구 | clerk api --platform <path> |
프로젝트는 clerk link를 통해 애플리케이션에 "연결"됩니다. 연결되면 대부분의 명령어는 저장소의 git 리모트에서 대상 앱과 개발 인스턴스를 자동으로 확인합니다. 다른 대상을 지정하려면 --app <id> 및/또는 --instance dev|prod|<instance_id>를 전달하세요. 전체 확인 순서는 references/auth.md를 참조하세요.
엔드포인트 발견 - 암기하지 마세요
CLI에는 Clerk OpenAPI 카탈로그가 포함되어 있습니다. 경로를 추측하는 대신 항상 동적으로 엔드포인트를 발견하세요.
clerk api ls # 모든 백엔드 API 엔드포인트 나열
clerk api ls users # 키워드로 필터링 (경로, 요약, 태그, operationId 일치)
clerk api ls --platform apps # 플랫폼 API 엔드포인트 나열
clerk api <path> 전에 이것을 사용하세요. 예상한 엔드포인트가 보이지 않으면 노출되지 않았을 가능성이 높습니다.
clerk api 명령어 (핵심 명령어)
clerk api는 인증된 HTTP 호출을 수행합니다. 키를 자동으로 확인하고, 본문 존재 여부에서 메서드를 자동 감지하며, stdin을 지원하고, --dry-run으로 변경 사항을 미리 볼 수 있습니다.
# GET 요청
clerk api /users # 사용자 목록
clerk api /users/user_abc123 # 단일 사용자 가져오기
clerk api /users?limit=5&order_by=-created_at # 쿼리 파라미터 인라인 사용
# 변경 요청
clerk api /users -d '{"email_address":["[email protected]"]}' # POST (본문에서 자동 감지)
clerk api /users/user_abc123 -X PATCH -d '{"first_name":"A"}'
clerk api /users/user_abc123 -X DELETE
# 파일 또는 stdin에서 본문 가져오기
clerk api /users --file payload.json
cat payload.json | clerk api /users
# 항상 변경 사항을 미리 보기
clerk api /users/user_abc123 -X DELETE --dry-run
clerk api /users/user_abc123 -X DELETE --yes # 확인 후 건너뛰기
# 특정 앱/인스턴스 대상 지정
clerk api /users --app app_abc123 --instance prod
# 디버깅 시 응답 헤더 포함
clerk api /users --include
# 플랫폼 API (계정 수준, 테넌트 데이터 아님)
clerk api /v1/platform/applications --platform
인스턴스 구성의 경우 원시 플랫폼 API /config 경로보다 전용 clerk config ... 명령어를 선호하세요. 이러한 명령어는 dry-run, diff, 확인을 원시 엔드포인트 형식보다 더 깔끔하게 처리합니다.
변경 전 항상 --dry-run을 먼저 실행하세요. 그런 다음 --dry-run 없이 다시 실행하고(확실하면 --yes 추가). 에이전트 모드에서는 대화형 확인이 우회되므로 --dry-run이 파괴적인 호출에 대한 유일한 안전망입니다.
JSON 본문은 유효한 JSON이어야 합니다. CLI는 잘못된 형식의 페이로드를 검증하고 거부합니다.
엔드포인트 경로는 /v1/ 접두사가 있거나 없이 제공될 수 있습니다 - 백엔드 API 호출에 대해 둘 다 작동합니다. CLI가 정규화합니다.
구체적인 패턴(사용자 목록/필터링, 조직 생성, 가장 세션 등)은 references/recipes.md를 참조하세요.
대용량 출력 검사 (컨텍스트를 넘치게 하지 마세요)
users list, apps list, config pull 및 대부분의 clerk api GET은 몇 킬로바이트에서 메가바이트에 달하는 페이로드를 반환합니다. 프로덕션 테넌트는 일반적으로 수천 명의 사용자를 보유하며, 인스턴스 구성은 수백 개의 필드로 깊을 수 있습니다. 이러한 응답을 대화에 읽어들이면 컨텍스트 창이 낭비됩니다. 먼저 응답을 파일에 저장한 다음 jq로 필요한 부분만 질의하세요.
# 1. 응답을 저장합니다. 사용자 목록의 페이지 크기를 최대화하려면 --limit 250을 사용하세요.
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. 필요한 부분만 검사합니다.
jq '.data | length' /tmp/users.json # 현재 페이지 크기
jq '.hasMore' /tmp/users.json # 추가 페이지 사용 가능 여부
jq '.data[0] | keys' /tmp/users.json # 사용자 구조를 한 번 발견
jq '.data[] | {id, email_addresses}' /tmp/users.json // 몇 개 필드로 프로젝션
jq '[.data[] | select(.banned)] | length' /tmp/users.json // 행을 읽지 않고 집계
jq를 사용할 수 없는 경우 Python 또는 Node로 대체하세요. 둘 다 파일 전체를 출력하지 않고 스트리밍할 수 있습니다.
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 하세요. 페이지를 탐색할 때 각 페이지를 자체 파일(예: page-${offset}.json)에 저장하여 개별 페이지를 독립적으로 검사 가능하게 유지하세요.
핵심 명령어 한눈에 보기
| 명령어 | 용도 | 주요 플래그 |
|---|---|---|
clerk init | 프로젝트에 Clerk를 스캐폴딩합니다. --starter는 Next.js, React Router, Astro, Nuxt, TanStack Start, React, Vue 및 JavaScript에 대한 부트스트랩만 지원합니다. | --framework, --pm, --name (--starter와 함께), --app, --starter, -y, --no-skills |
clerk auth login | OAuth 브라우저 로그인(토큰 저장). 에이전트 모드: 이미 로그인된 경우 아무 작업도 하지 않습니다. 저장된 세션이 없어도 브라우저를 열고 localhost 콜백을 바인딩하므로 무인 실행이 불가능합니다. 무인 흐름에는 CLERK_PLATFORM_API_KEY를 선호하세요. 별칭: signup, signin, sign-in. 최상위 단축키: clerk login. | - |
clerk auth logout | 저장된 자격 증명을 지웁니다. 별칭: signout, sign-out. 최상위 단축키: clerk logout. | - |
clerk whoami | 로그인된 이메일을 출력합니다. |