CLI 명령어¶

이 문서에서는 OWL CLI의 주요 명령어를 소개합니다. 설정 및 인증, 도구 디렉터리 동기화, 도구 조회, 실행 전 검증, 도구 실행, 캐시 관리, 데이터 파일 관리, 그리고 Agent 대상 기능 협상 및 Schema 출력을 다룹니다.

설정 및 인증¶

OWL CLI는 다음과 같은 주요 설정을 사용합니다:

주요 명령어:

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

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

액세스 토큰을 설정할 때, api-key와 token 키 이름은 동일하며, 어느 하나를 기록해도 동일한 액세스 토큰이 업데이트됩니다. 워크스페이스 수준 토큰도 동일한 규칙을 따릅니다.

owl workspace same-org list¶

현재 계정과 동일한 조직의 워크스페이스를 나열합니다. 지원되는 플래그:

페이지네이션 규칙:

• 기본적으로 한 페이지만 반환합니다. 더 많은 결과가 있으면 텍스트 출력에 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와 동일한 네 가지 매개변수 형식을 허용하지만, 도구 존재 여부, 매개변수 Schema 및 도구 전용 문법만 검증하고 대상 도구를 실행하지는 않습니다:

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는 공식 요청 전에도 동일한 매개변수 Schema 검증을 수행합니다. 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
  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. config.yaml

캐시 및 동기화¶

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를 유추하거나 추측하지 마세요. owl data list -f json을 실행하여 공식 ID를 얻고, 해당 항목을 찾은 후 files[].id를 저장한 다음, 해당 값을 그대로 owl data show 또는 owl data rm에 전달하세요.

주요 데이터 파일 명령어:

Agent 대상 Schema 출력¶

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

owl schema

지정된 분류만 내보내기:

owl schema -c metric

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

• owl_exec: 모든 OWL 도구를 통합 실행
• owl_list_categories: 분류 나열
• owl_list_tools: 도구 나열
• 현재 동기화된 도구 정의

Agent에 연결하기 전에 먼저 owl sync를 한 번 실행하여 로컬 Schema가 플랫폼의 현재 도구 디렉터리와 일치하는지 확인하는 것이 좋습니다.

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

도움말 명령어¶

OWL CLI 도움말 조회:

owl --help

지정된 명령어 도움말 조회:

owl help exec
owl help sync
owl help data