CLI 명령¶

이 문서에서는 OWL CLI의 일반적인 명령어를 설명합니다. 설정 및 인증, 도구 카탈로그 동기화, 도구 조회, 실행 전 검증, 도구 실행, 캐시 관리, 데이터 파일 관리, Agent 대상 기능 협의 및 스키마 출력을 다룹니다.

설정 및 인증¶

OWL CLI는 다음과 같은 일반적인 설정을 사용합니다.

일반적인 명령어:

owl init
owl login
owl config show
owl config set registry.endpoint "your-owl-endpoint"

전역 --conf <path> 파라미터를 사용하면 단일 명령에 대해 이미 존재하는 다른 설정 파일을 선택할 수 있으며, 서로 다른 권한 또는 Endpoint 간 전환에 적합합니다.

owl --conf ~/.owl/prod.yaml config show
owl --conf ~/.owl/prod.yaml sync
owl --conf ~/.owl/prod.yaml exec owl.metric.list --mode source

init, login, config set, workspace use 등의 쓰기 작업은 --conf로 지정된 파일에 다시 기록합니다. 이 파라미터를 전달하지 않으면 OWL은 계속 ${OWL_DIR}/config.yaml을 사용합니다. 기본 경로는 $HOME/.owl/config.yaml입니다.

로컬 개발 환경의 Registry가 자체 서명 인증서를 사용하는 경우, 인증서 검증을 명시적으로 비활성화할 수 있습니다.

owl config set registry.insecure_skip_verify true
# 또는 현재 프로세스에만 적용
export OWL_REGISTRY_INSECURE_SKIP_VERIFY=true

이 설정의 기본값은 false입니다. 활성화하면 OWL이 Registry의 ID를 확인할 수 없으므로 중간자 공격의 위험이 있으며, 프로덕션 환경에서 사용해서는 안 됩니다.

workspace 명령어는 별칭 workspaces로도 사용할 수 있습니다.

액세스 토큰을 설정할 때 api-key와 token이라는 두 키 이름은 동일하며, 둘 중 하나를 작성하면 동일한 액세스 토큰이 업데이트됩니다. 워크스페이스 수준 토큰도 동일한 동등 규칙을 따릅니다.

owl workspace same-org list¶

현재 계정과 동일 조직(same-org)의 워크스페이스를 나열합니다. 지원되는 flags:

페이지네이션 규칙:

• 기본적으로 한 페이지만 반환합니다. 더 많은 결과가 있는 경우 텍스트 출력은 More results available. Fetch the next page with --before-id <id>를 표시하며, 여기서 <id>는 서버가 반환한 다음 페이지의 커서입니다.
• --all을 추가하면 CLI는 서버가 반환한 커서에 따라 자동으로 다음 페이지를 반복해서 가져오며, 더 이상 결과가 없을 때까지 계속합니다. 커서가 더 이상 진행되지 않으면 중지되어 비정상적인 서버에 의한 무한 루프를 방지합니다.

예시:

owl workspace same-org list
owl workspace same-org list --page-size 50
owl workspace same-org list --before-id 12345
owl workspace same-org list --uuid wksp_xxx --uuid wksp_yyy
owl workspace same-org list --all

환경 변수는 로컬 설정 파일보다 우선순위가 높습니다. 현재 터미널에 OWL_REGISTRY_ENDPOINT, OWL_API_KEY 또는 OWL_TOKEN이 이미 설정된 경우 OWL CLI는 환경 변수 값을 우선 사용합니다. OWL_API_KEY와 OWL_TOKEN이 동시에 존재하는 경우 OWL_API_KEY가 우선 적용됩니다.

카테고리 및 도구 카탈로그¶

카테고리 및 도구를 조회하기 전에 먼저 동기화를 한 번 실행하는 것이 좋습니다.

owl sync

카테고리 및 도구 조회 명령어:

owl category list
owl category show metric
owl list
owl list -c metric
owl show owl.metric.list

도구 실행¶

owl exec를 사용하여 도구를 실행합니다.

owl exec <도구 이름> [파라미터]

도구 이름은 owl list에 표시된 이름과 일치해야 합니다. 실행 전에 owl show <도구 이름>을 사용하여 파라미터 정의를 확인할 수 있습니다.

파라미터 전달 방식¶

owl exec는 다음 네 가지 파라미터 전달 방식을 지원합니다.

--key value 사용¶

owl exec owl.metric.list --mode source

key=value 사용¶

owl exec owl.metric.list mode=source

-p로 JSON 전달¶

owl exec owl.metric.list -p '{"mode":"source"}'

표준 입력에서 JSON 읽기¶

echo '{"mode":"source"}' | owl exec owl.metric.list --stdin

실행 규칙¶

도구 실행 시 다음 사항에 유의하세요.

• 도구 이름은 owl list에 표시된 이름과 일치해야 합니다.
• 필수 파라미터는 모두 제공해야 합니다.
• 파라미터 이름은 도구 정의와 일치해야 합니다.
• 파라미터 유형은 도구 정의와 일치해야 합니다.
• 반환 결과의 표시 여부는 OWL_TOKEN에 해당하는 API Key 권한에 따라 달라집니다.

예시: 메트릭 소스 조회¶

owl show owl.metric.list
owl exec owl.metric.list --mode source

예시: 이벤트 목록 조회¶

owl show owl.event.list
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20

실행 전 검증 및 기능 협의¶

1.2.0부터는 정식 실행 전에 owl validate를 사용하여 도구 호출을 한 번 검증할 수 있습니다. 이 명령어는 owl exec와 동일한 네 가지 파라미터 형식을 허용하지만, 도구 존재 여부, 파라미터 스키마 및 도구 전용 구문만 검증하고 대상 도구를 실행하지는 않습니다.

owl validate owl.metric.list --mode source
owl validate owl.data.query -p '{"query_text":"L::re(`.*`):(count(*)) [5m]","query_mode":"dql"}' -f json

JSON 결과에는 다음이 포함됩니다.

• valid: 호출이 검증을 통과했는지 여부
• tool: 검증된 도구 이름
• request_executed: 항상 false로 고정, 대상 도구가 실행되지 않았음을 확인
• issues: 구조화된 문제 목록, 알 수 없는 도구, 누락된 파라미터, 유형 오류, 알 수 없는 파라미터 또는 DQL 구문 문제 포함 가능

검증 통과 실패(valid: false) 시에도 명령 프로세스는 0 상태 코드로 종료됩니다. Agent는 JSON을 요청하고 결과를 파싱해야 하며, valid가 true인 경우에만 owl exec를 실행할 수 있습니다. 0이 아닌 상태 코드는 검증이 완료되지 않았음을 의미하며, 실행이 허용되는 것으로 간주할 수 없습니다.

owl.data.query의 DQL 모드는 Registry의 DQL 검증 기능을 호출합니다. PromQL 모드는 DQL 검증기에 진입하지 않습니다. 1.2.1부터 owl.data.simple_query 및 owl.data.simple_query_file도 간소화된 파라미터에서 생성된 DQL을 검증합니다. 실패 시 generated_dql / dql.builderError를 반환하며, select_clause, where_clause 또는 group_by_clause를 수정한 후 재시도해야 합니다.

owl exec는 정식 요청 전에도 동일한 파라미터 스키마 검증을 수행합니다. Agent runtime이 현재 CLI가 사전 검증을 지원하는지 확인해야 하는 경우 다음을 실행할 수 있습니다.

owl capabilities -f json

현재 기능 응답 버전은 owl.capabilities/v1이며, 사전 검증 기능 식별자는 tool.validate/v1입니다. owl tool validate, owl tools validate, owl tool capabilities 및 owl tools capabilities는 해당하는 네임스페이스 별칭입니다.

설정 파일 및 우선순위¶

기본 설정 파일 경로:

설정 파일 예시:

registry:
  endpoint: your-owl-endpoint
  insecure_skip_verify: false
  request_timeout: 150000
  sync_interval: 3600

auth:
  token: ""

cache:
  directory: ~/.owl/cache
  ttl: 86400

data:
  directory: ~/.owl/data
  max_age_days: 1

sync:
  parallel: true
  concurrency: 5
  incremental: true

execution:
  default_timeout: 30000
  max_output_size: 10485760

logging:
  level: info
  file: ~/.owl/logs/owl.log

설정 우선순위는 높은 순서에서 낮은 순서로 다음과 같습니다.

1. 환경 변수
2. --conf로 지정된 설정 파일(해당 파라미터 설정 시)
3. ${OWL_DIR}/config.yaml(--conf 미설정 시)

registry.request_timeout은 단일 Registry HTTP 요청의 전체 타임아웃을 제어하며, 단위는 밀리초입니다. 기본값 150000은 데이터 조회 도구의 130초 서버 측 기한보다 높으며, 응답 인코딩 및 네트워크 전송 시간을 확보합니다. 업스트림 쿼리 소요 시간을 명확히 알고 있는 경우에만 조정하세요.

캐시 및 동기화¶

owl sync는 Guance의 카테고리 및 도구 메타데이터를 로컬 캐시 디렉터리에 동기화합니다.

다음 시나리오에서는 owl sync를 다시 실행해야 합니다.

• 최초 설치 완료 후
• 플랫폼에 새 도구가 게시된 경우
• 플랫폼이 기존 도구의 파라미터 또는 설명을 업데이트한 경우
• 로컬 캐시 내용을 새로고침해야 하는 경우

일반적인 동기화 및 캐시 명령어:

버전 업데이트 알림¶

설치 프로그램을 사용하여 업데이트 채널을 구성한 경우, owl exec는 최대 24시간마다 새 버전을 확인합니다. 새 버전이 발견되면 JSON 결과에 notice 필드가 추가되며, 기존 success, output, file 등의 필드는 변경되지 않습니다. 확인 실패는 도구 실행을 차단하지 않습니다.

다음 명령어를 실행하여 현재 업데이트 채널로 업그레이드할 수 있습니다.

owl update

자동 확인을 비활성화하려면 설정 파일에서 update.check: false로 설정하세요. 업데이트 채널이 구성되지 않은 설치는 확인을 수행하지 않으며, 알림도 출력되지 않습니다.

데이터 결과 파일¶

도구 정의의 출력 유형이 data인 경우 OWL CLI는 자동으로 결과 파일을 로컬 data/ 디렉터리에 저장하고 파일 인덱스 및 구조 정보를 기록합니다. 1.2.1부터 새 파일은 22자리 URL-safe 랜덤 ID를 사용하여 Agent가 참조하기 쉽도록 하고 긴 파일 이름의 위험을 줄입니다. 안정적인 queryKey 및 기존 인덱스 형식은 변경되지 않습니다.

owl exec의 JSON 결과에서 file은 path, absolutePath, format 및 size만 포함하며, 데이터 파일 id는 포함하지 않습니다. 경로에서 ID를 유추하거나 추측하지 마세요. 권위 있는 ID를 얻으려면 owl data list -f json을 실행하고, 해당 항목을 찾은 후 files[].id를 저장한 다음 해당 값을 owl data show 또는 owl data rm에 그대로 전달하세요.

일반적인 데이터 파일 명령어:

Agent 대상 스키마 출력¶

OWL CLI를 사용자 정의 Agent에 연결해야 하는 경우 함수 호출 스키마를 내보낼 수 있습니다.

owl schema

지정된 카테고리만 내보내기:

owl schema -c metric

owl schema의 출력에는 다음이 포함됩니다.

• owl_exec: 임의의 OWL 도구를 통합 실행
• owl_list_categories: 카테고리 나열
• owl_list_tools: 도구 나열
• 현재 동기화된 도구 정의

Agent에 연결하기 전에 먼저 owl sync를 한 번 실행하여 로컬 스키마가 플랫폼의 현재 도구 카탈로그와 일치하는지 확인하는 것이 좋습니다.

대상 클라이언트가 MCP를 지원하는 경우 MCP Server 빠른 시작의 원격 MCP Server 연결 방식을 우선 사용하세요.

도움말 명령어¶

OWL CLI 도움말 보기:

owl --help

지정된 명령어의 도움말 보기:

owl help exec
owl help sync
owl help data