CLI 빠른 시작¶

이 문서는 OWL CLI를 처음 사용하는 사용자를 대상으로 OWL CLI 설정, 도구 디렉터리 동기화 및 도구 호출 실행 방법을 설명합니다.

전제 조건¶

시작하기 전에 다음 사항을 확인하세요.

OWL 수동 설치 또는 OWL 자동 설치를 완료했습니다.
워크스페이스가 속한 사이트에 해당하는 OWL CLI Endpoint를 획득했습니다. Endpoint 목록을 참조하세요.
액세스 토큰 OWL_TOKEN 또는 OWL_API_KEY를 획득했습니다. 해당 내용은 DF-API-KEY를 참조하세요.
현재 터미널에서 OWL CLI Endpoint에 접근할 수 있습니다.

1단계: Endpoint 및 액세스 토큰 설정¶

OWL CLI는 환경 변수 또는 로컬 설정 파일을 통해 Endpoint와 액세스 토큰을 설정할 수 있습니다.

OWL_REGISTRY_ENDPOINT는 Endpoint 기본 주소만 입력하고, /api/v1 등의 경로를 직접 추가하지 마세요.

방법 1: 환경 변수 사용¶

bash / zshPowerShell

export OWL_REGISTRY_ENDPOINT="your-owl-endpoint"
export OWL_TOKEN="your-token"

$env:OWL_REGISTRY_ENDPOINT = "your-owl-endpoint"
$env:OWL_TOKEN = "your-token"

환경 변수는 현재 터미널 세션에서만 유효합니다. 터미널을 종료한 후에도 계속 사용하려면 다시 설정해야 합니다.

액세스 토큰은 OWL_API_KEY로도 설정할 수 있습니다. OWL_API_KEY와 OWL_TOKEN이 동시에 존재하는 경우, OWL CLI는 OWL_API_KEY를 우선합니다.

방법 2: 로컬 설정 파일에 작성¶

owl init
owl login

실행 설명:

owl init은 OWL CLI Endpoint를 작성하는 데 사용됩니다.
owl login은 액세스 토큰을 작성하는 데 사용됩니다.

로컬 설정은 OWL CLI 설정 디렉터리에 저장되며, 이후 새 터미널을 열어도 계속 사용할 수 있습니다.

환경 변수의 우선순위가 설정 파일보다 높습니다. 현재 터미널에 환경 변수가 이미 설정된 경우, OWL CLI는 환경 변수의 값을 우선 사용합니다.

2단계: 도구 디렉터리 동기화¶

OWL CLI를 처음 사용하기 전에 먼저 도구 디렉터리를 동기화해야 합니다.

owl sync

owl sync는 Guance에서 현재 사용 가능한 분류와 도구 메타데이터를 로컬 캐시에 동기화합니다. 동기화가 완료된 후에야 도구를 확인하고 실행할 수 있습니다.

특정 분류만 동기화하려면 -c를 사용하여 분류를 지정합니다.

owl sync -c data

3단계: 도구 확인¶

모든 도구 분류 확인:

owl category list

특정 분류의 도구 확인:

owl list -c data

특정 도구의 매개변수 설명 확인:

owl show owl.data.query

4단계: 실행 전 검증¶

실제 쿼리를 수행하지 않고 먼저 도구 호출을 검증합니다.

owl validate owl.data.show_dql_namespace -f json

결과에서 valid는 true, request_executed는 false여야 합니다. 현재 CLI가 validate를 지원하지 않는 경우 1.2.0 이상 버전으로 업그레이드하세요.

5단계: 도구 실행¶

다음 명령을 실행하여 현재 워크스페이스에서 지원하는 DQL 네임스페이스를 확인합니다. (owl.data.query 사용 전 첫 번째 단계입니다.)

owl exec owl.data.show_dql_namespace

머신이 읽을 수 있는 출력이 필요한 경우 JSON 형식을 지정할 수 있습니다.

owl exec owl.data.show_dql_namespace -f json

전체 예시¶

bash / zshPowerShell

export OWL_REGISTRY_ENDPOINT="your-owl-endpoint"
export OWL_TOKEN="your-token"

owl sync
owl category list
owl list -c data
owl show owl.data.query
owl validate owl.data.show_dql_namespace -f json
owl exec owl.data.show_dql_namespace -f json

$env:OWL_REGISTRY_ENDPOINT = "your-owl-endpoint"
$env:OWL_TOKEN = "your-token"

owl sync
owl category list
owl list -c data
owl show owl.data.query
owl validate owl.data.show_dql_namespace -f json
owl exec owl.data.show_dql_namespace -f json

성공 기준¶

빠른 시작을 완료한 후 다음 결과를 확인할 수 있어야 합니다.

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 네임스페이스를 반환할 수 있습니다.

인증 실패, 도구 없음, 결과 없음 등의 문제가 발생하는 경우 문제 해결을 참조하세요.