CLI 빠른 시작¶
이 문서는 OWL CLI를 처음 사용하는 사용자를 대상으로 OWL CLI 구성, 도구 카탈로그 동기화, 도구 호출 1회 실행 방법을 소개합니다.
Codex, Claude Code, Cursor, Trae, GitHub Copilot(VS Code) 또는 Windsurf 등의 Agent 대화에서 직접 사용하려면 먼저 통합 자동 설치 절차에 따라 CLI와 함께 제공되는 Skill을 설치한 다음 첫 호출 검증을 완료하면 됩니다. 이 페이지에서는 명령을 수동으로 실행하는 절차를 설명합니다. 자동 설치에서 완료된 구성 및 동기화 단계는 반복할 필요가 없습니다.
사전 요구 사항¶
시작하기 전에 다음을 확인하세요:
- OWL 수동 설치 또는 OWL 자동 설치를 완료했습니다.
- 워크스페이스가 속한 사이트에 해당하는 OWL CLI Endpoint를 확보했습니다. Endpoint 목록을 참고할 수 있습니다.
- Studio의 개인 API 키 페이지에서 임시 인증 코드를 생성했거나, 계속 사용할 수 있는 API Key 구성이 있습니다.
- 현재 터미널에서 OWL CLI Endpoint에 접근할 수 있습니다.
1단계: 로그인 및 워크스페이스 구성¶
OWL CLI 1.9.0 이상을 사용하고, 소속 사이트가 DPoP를 지원하는지 확인합니다. owl init은 사이트의 HTTPS Endpoint를 저장합니다. owl login --dpop은 안내에 따라 Studio 임시 인증 코드를 읽고, 바인딩된 자격 증명을 로컬에 저장합니다. 워크스페이스를 전환해야 할 때는 owl workspace use <workspace_uuid>를 실행합니다.
추가 및 전환¶
먼저 계정 A로 Studio에 로그인하고, 「개인 API 키」 페이지에서 임시 인증 코드를 생성합니다. owl profile add customer-a를 실행하고 안내에 따라 소속 사이트의 HTTPS Registry 주소와 임시 코드를 입력합니다. 그런 다음 계정 B에서 생성한 새 코드로 B를 추가합니다. 임시 코드를 입력할 때 터미널에는 내용이 표시되지 않습니다. 사이트 주소 보기
owl profile add customer-a
owl switch customer-a
owl profile add customer-b
owl --profile customer-b sync
B를 추가한 후에도 기본 계정은 A입니다. --profile customer-b는 현재 명령에만 B를 선택합니다. owl switch customer-b를 실행하면 이후 명령에서 B를 사용할 수 있습니다. 계정을 추가하려면 임시 코드를 온라인에서 교환해야 하며, 전환 시에는 로컬 구성만 확인합니다. 여러 Profile 사용.
API Key 모드¶
기존 API Key 구성은 owl login, OWL_TOKEN 또는 OWL_API_KEY를 계속 사용할 수 있습니다. 환경 변수 방식은 레거시 구성 모드이거나 --conf를 단독으로 사용할 때만 ID를 재정의하며, OWL_API_KEY가 OWL_TOKEN보다 우선합니다. DPoP 로그인을 사용하기 전에 API Key 모드 선택에 사용되는 ID 환경 변수를 해제하세요.
2단계: 도구 카탈로그 동기화¶
OWL CLI를 처음 사용하기 전에 도구 카탈로그를 먼저 동기화해야 합니다:
owl sync는 Guance에서 현재 사용 가능한 카테고리와 도구 메타데이터를 로컬 캐시에 동기화합니다. 동기화가 완료된 후에만 도구를 확인하고 실행할 수 있습니다.
특정 카테고리만 동기화하려면 -c로 카테고리를 지정할 수 있습니다:
3단계: 도구 보기¶
모든 도구 카테고리 보기:
특정 카테고리의 도구 보기:
특정 도구의 파라미터 설명 보기:
4단계: 실행 전 검증¶
실제 쿼리를 수행하지 않은 상태에서 먼저 도구 호출을 검증합니다:
결과의 valid는 true, request_executed는 false여야 합니다. 현재 CLI가 validate를 지원하지 않으면 1.2.0 이상으로 업그레이드하세요.
5단계: 도구 실행¶
다음 명령을 실행하여 현재 워크스페이스에서 지원하는 DQL 네임스페이스를 확인합니다(owl.data.query 사용 전의 첫 단계입니다):
기계 판독 가능한 출력이 필요하면 JSON 형식을 지정할 수 있습니다:
전체 예시(API Key)¶
성공 기준¶
빠른 시작을 완료한 후 다음 결과를 얻을 수 있어야 합니다:
owl sync가 정상적으로 완료되고 인증 또는 네트워크 오류가 반환되지 않습니다.owl category list에서 도구 카테고리를 볼 수 있습니다.owl list -c data에서data카테고리의 도구를 볼 수 있습니다.owl validate owl.data.show_dql_namespace -f json가valid: true와request_executed: false를 반환합니다.owl exec owl.data.show_dql_namespace가 현재 워크스페이스에서 지원하는 DQL 네임스페이스를 반환합니다.
인증 실패, 도구 없음, 빈 결과 등의 문제가 발생하면 문제 해결을 참조하세요.