CLI 명령¶
이 문서에서는 OWL CLI의 주요 명령을 소개합니다. 설정 및 인증, 도구 카탈로그 동기화, 도구 조회, 실행 전 검증, 도구 실행, 캐시 관리, 데이터 파일 관리, 그리고 Agent 대상 기능 협상 및 스키마 출력을 포함합니다.
명령줄 자동 완성¶
Bash¶
Bash 3.2 및 Bash 4/5를 지원하며 Linux, macOS, Windows Git Bash 및 WSL에서 사용할 수 있습니다. WSL에서는 Linux 버전 OWL을 사용하고, Git Bash에서는 Windows 버전 owl.exe를 사용하며 owl 또는 owl.exe를 입력할 수 있습니다.
먼저 Bash 버전과 호환되는 bash-completion을 설치하고 로드합니다. Bash 3.2는 호환되는 1.x 버전을 사용하고, Bash 4/5는 해당하는 2.x 버전을 사용합니다. 현재 터미널에서 OWL 자동 완성을 활성화합니다:
영구적으로 활성화하려면 동일한 줄을 ~/.bashrc에서 bash-completion을 로드하는 코드 뒤에 추가합니다. 로그인 터미널이 ~/.bash_profile만 읽는 경우 해당 파일이 ~/.bashrc를 로드하는지 확인합니다. 한 번만 설정하고 중복 추가하지 마세요.
여기에서는 eval을 사용해 OWL이 생성한 스크립트를 로드하여 일부 macOS Bash 3.2 환경에서 source <(...)가 조용히 로드되지 않는 문제를 방지합니다. 아래 설명대로 스크립트를 파일로 저장한 뒤 source할 수도 있습니다.
설치 스크립트는 여전히 생성된 자동 완성 스크립트를 ~/.local/share/bash-completion/completions/owl에 기록합니다. 현재 bash-completion이 이 디렉터리를 자동으로 로드하면 위 시작 명령을 추가로 설정할 필요가 없습니다. OWL을 업데이트한 후에는 기존 정적 자동 완성 파일을 다시 생성해야 합니다:
mkdir -p ~/.local/share/bash-completion/completions
owl completion bash > ~/.local/share/bash-completion/completions/owl
source ~/.local/share/bash-completion/completions/owl
PowerShell¶
Windows PowerShell 5.1 및 PowerShell 7은 전용 자동 완성 스크립트를 사용하며 동일한 로컬 도구 후보 로직을 공유합니다. 현재 터미널에서 활성화합니다:
영구적으로 활성화하려면 이 줄을 $PROFILE에 추가할 수 있습니다. 기존 Windows 설치 스크립트는 이미 Completions\owl.ps1을 생성하고 설치 시 사용하는 $PROFILE에서 이를 로드합니다. 이미 설정한 사용자는 중복 추가할 필요가 없습니다. PowerShell 버전이나 호스트에 따라 다른 profile을 사용할 수 있으므로 실제 사용하는 터미널에서 활성화하세요.
CMD는 이번 자동 완성 지원 범위에 포함되지 않습니다.
자동 완성 내용 및 캐시¶
먼저 일반 명령으로 도구 정의를 동기화합니다:
다음 예시에서 <Tab>은 Tab 키를 누르는 것을 의미합니다:
owl exec owl.met<Tab> → owl.metric.list
owl exec owl.metric.list --mo<Tab> → --mode
owl exec owl.metric.list mo<Tab> → mode=
owl exec owl.metric.list --mode s<Tab> → source
owl exec owl.metric.list --mode=s<Tab> → --mode=source
owl exec owl.metric.list mode=s<Tab> → mode=source
- 도구 이름 뒤에서 바로 Tab을 누르면 기본적으로
--파라미터명이 나열되고, 일반 이름 접두사를 입력하면파라미터명=이 나열됩니다. exec,validate및 해당tool/tools진입점을 지원합니다.show는 도구 이름 자동 완성을,--category는 카테고리 자동 완성을,--format은 형식 자동 완성을 지원합니다.- 파라미터 값은 스키마의 문자열, 숫자 또는 불리언 열거형에서 가져오며, 불리언 파라미터는
true/false를 제안합니다. 자유 텍스트, 배열, 객체 및-p/--params뒤의 JSON 내용은 자동 완성하지 않습니다. - 이미 입력한 도구 파라미터는 다시 제안하지 않습니다. 워크스페이스, 메트릭 소스, 필드 등의 실시간 비즈니스 데이터는 조회하지 않습니다.
- Tab은 현재 설정에서 선택한 로컬 캐시만 읽으며, 네트워크에 연결하지 않고, 도구를 실행하지 않으며, 표준 입력을 읽지 않고, 설정을 쓰지 않고, 이전 캐시를 마이그레이션하지 않습니다.
OWL_DIR및 명령 앞의--conf로 설정과 캐시를 선택할 수 있습니다. - Profile 별칭은
owl switch <Tab>,owl profile rename/remove <Tab>,owl --profile <Tab>, 그리고owl exec --profile=<Tab>등 도구 이름 앞의 옵션을 지원합니다. 새 별칭과 이름 변경 시 새 이름은 사용자가 입력하며 파일을 제안하지 않습니다.profile add --from은 설정 파일 자동 완성을 유지합니다. - 도구 후보는 현재 Profile의 설정 및 캐시 격리를 따릅니다.
--profile,OWL_PROFILE및 전환된 기본 Profile이 모두 적용됩니다.owl exec --profile <이름> <도구명>도 지원하며, 도구 이름 뒤의--profile은 여전히 도구 파라미터에 속합니다. - 캐시가 비어 있거나 설정을 읽을 수 없어도 기본 명령과 고정 옵션은 자동 완성할 수 있습니다. 도구 정의 자동 완성은
owl sync를 성공적으로 실행한 후 사용할 수 있습니다. 동기화가 완료된 후 자동 완성 스크립트를 다시 로드할 필요가 없습니다.
Bash에서 _get_comp_words_by_ref: command not found가 표시되면 bash-completion이 아직 로드되지 않은 것입니다. 도구 이름 또는 파라미터 후보만 누락된 경우 현재 설정에서 owl list와 owl show <도구명>이 도구 정의를 읽을 수 있는지 먼저 확인한 후 owl sync를 실행하여 캐시를 업데이트하세요.
방금 소스에서 빌드한 경우 먼저 command -v owl로 현재 터미널에서 새 버전을 호출하는지 확인합니다. make build는 build/owl만 생성하며 기존 설치를 덮어쓰지 않습니다. 자동 완성 스크립트를 로드해도 실행 파일이 교체되지 않습니다. 저장소 루트에서 export PATH="$PWD/build:$PATH" 및 hash -r을 실행한 후 활성화 명령을 다시 실행하세요. complete -p owl로 Bash에 자동 완성이 등록되었는지 확인할 수 있습니다.
DPoP 로그인¶
OWL CLI 1.9.0 이상을 사용하고 소속 사이트가 DPoP를 지원하는지 확인합니다. owl init은 사이트의 HTTPS Endpoint를 저장합니다. owl login --dpop는 안내에 따라 Studio 임시 인증 코드를 읽고 로컬에 바인딩된 자격 증명을 저장합니다. 워크스페이스를 전환해야 하는 경우 owl workspace use <workspace_uuid>를 실행합니다.
기존 API Key 설정은 owl login, OWL_TOKEN 또는 OWL_API_KEY를 계속 사용할 수 있습니다. 환경 변수 방식은 이전 설정 모드이거나 --conf를 단독으로 사용할 때만 ID를 재정의하며, OWL_API_KEY가 OWL_TOKEN보다 우선합니다. DPoP 로그인을 사용하기 전에 API Key 모드를 선택하는 데 사용되는 ID 환경 변수를 해제하세요.
--from은 파일의 사이트 주소, 타임아웃 등 ID가 아닌 설정을 그대로 사용할 수 있지만, 새 계정의 임시 인증 코드로 로그인해야 합니다. 원본 파일의 API Key, token_file 및 DPoP 바인딩은 새 Profile에 복사되지 않으며 원본 파일은 변경되지 않습니다. 여러 Profile 사용.
설정 및 인증¶
OWL CLI에서 자주 사용하는 설정은 다음과 같습니다:
| 구성 항목 | 설명 |
|---|---|
OWL_REGISTRY_ENDPOINT |
워크스페이스가 속한 사이트에 대응하는 OWL CLI Endpoint |
OWL_REGISTRY_INSECURE_SKIP_VERIFY |
true로 설정하면 Registry HTTPS 인증서 검증을 건너뛰며, 로컬 개발 또는 자체 서명 인증서 환경에서만 사용합니다 |
OWL_REGISTRY_REQUEST_TIMEOUT |
Registry HTTP 요청 총 타임아웃, 단위 밀리초, 기본값 150000 |
OWL_TOKEN |
이전 버전 인증 환경 변수로 DF-API-KEY에 대응합니다. 이전 설정 모드이거나 --conf를 단독으로 사용할 때만 ID를 재정의합니다 |
OWL_API_KEY |
인증 API Key 환경 변수입니다. 사용 사례는 OWL_TOKEN과 동일하며 동시에 설정하면 OWL_TOKEN보다 우선합니다 |
OWL_TEMP_CODE |
Studio 일회용 임시 인증 코드로, 설치 스크립트와 owl login --dpop에서 사용합니다 |
OWL_DIR |
기본 설정/캐시/데이터 루트 디렉터리를 재정의합니다. 기본값은 $HOME/.owl이며 ~를 사용해 확장할 수 있습니다 |
OWL_PROFILE |
이번 프로세스에 저장된 Profile을 선택합니다. 우선순위는 --profile보다 낮고 영구 저장된 선택보다 높습니다 |
자주 사용하는 명령:
여러 개의 독립 설정을 저장하고 별칭으로 선택할 수 있습니다:
owl profile add customer-a
owl switch customer-a
owl profile add customer-b --from ./customer-b.yaml
owl profile list
owl --profile customer-b exec owl.data.show_dql_namespace
owl profile current -f json
B를 추가한 후에도 기본 계정은 여전히 A입니다. --profile customer-b는 현재 명령에만 B를 선택합니다. owl switch customer-b를 실행하면 이후 명령에서 B를 사용할 수 있습니다. 계정 추가 시에는 온라인으로 임시 코드를 교환해야 하며, 전환은 로컬 설정만 확인합니다.
Profile을 선택하면 Endpoint와 자격 증명은 해당 Profile에서 가져오며, ID 환경 변수로 덮어쓸 수 없습니다. ID가 아닌 환경 설정은 계속 적용됩니다. OWL_PROFILE이 설정된 경우 해당 변수를 먼저 해제해야 owl switch를 실행할 수 있습니다. 요청 실패 시 다른 Profile로 자동 전환하지 않습니다. 여러 Profile 사용.
CLI의 --conf <path>는 더 이상 사용되지 않으며 도움말에서 숨겨졌습니다. 호환 기간에는 여전히 지정된 파일을 읽고 쓰며 환경 변수 재정의를 유지합니다. --profile과 함께 전달하면 오류가 발생합니다. profile add <alias> --from <path>로 가져온 후 --profile을 사용하도록 권장합니다. Registry의 --config는 계속 사용할 수 있습니다.
로컬 개발 환경의 Registry가 자체 서명 인증서를 사용하는 경우 인증서 검증을 명시적으로 끌 수 있습니다:
owl config set registry.insecure_skip_verify true
# 또는 현재 프로세스에만 적용
export OWL_REGISTRY_INSECURE_SKIP_VERIFY=true
이 설정의 기본값은 false입니다. 활성화하면 OWL이 Registry의 ID를 검증할 수 없어 중간자 공격을 받을 수 있으므로 프로덕션 환경에서는 사용하지 않아야 합니다.
| 명령 | 설명 |
|---|---|
owl init |
OWL CLI Endpoint를 기록합니다 |
owl login --dpop |
Studio 임시 코드로 로그인하고 로컬에 바인딩된 자격 증명을 저장합니다 |
owl logout |
현재 DPoP 자격 증명을 취소합니다 |
owl login |
API Key 모드 |
owl config show |
현재 설정을 조회합니다 |
owl config set <구성 항목> <값> |
지정한 구성 항목을 수정합니다 |
owl profile add <alias> [--from <file>] |
Studio 임시 코드로 DPoP 계정을 추가합니다. --from은 사이트 및 ID가 아닌 설정만 제공합니다 |
owl profile list |
로컬 Profile, 실제 선택 및 영구 기본값을 나열합니다 |
owl profile current |
실제 적용되는 Profile, ID 소스 및 cache/data 경로를 표시합니다 |
owl switch <alias> |
이후 명령의 기본 Profile을 저장합니다 |
owl profile rename <old> <new> |
별칭 이름을 변경하고 설정 및 쿼리 파일 경로를 유지합니다 |
owl profile remove <alias> [--purge] |
로컬 Profile을 삭제하며 기본적으로 cache/data를 유지합니다. 자격 증명을 취소하려면 먼저 해당 Profile의 logout을 실행합니다 |
owl workspace list |
API Key 모드: 현재 계정에서 사용 가능한 워크스페이스 목록을 가져오고 각 워크스페이스의 이름과 workspace_uuid를 출력합니다 |
owl workspace use <workspace_uuid> |
DPoP 모드에서 대상 워크스페이스 UUID를 검증하고 선택을 저장합니다. API Key 모드에서는 대상 워크스페이스의 Key를 가져와 저장합니다 |
owl workspace current |
현재 워크스페이스 컨텍스트를 표시합니다 |
owl workspace key get <workspace_uuid\|workspace_name> |
API Key 모드: 지정한 워크스페이스의 액세스 키를 가져옵니다(기본적으로 마스킹되어 표시되며, --show-secret을 추가하면 원본 키를 출력합니다) |
owl workspace profile list |
선택한 설정의 workspaces 항목을 나열합니다 |
owl workspace profile current |
선택한 설정에서 현재 일치하는 워크스페이스 항목을 표시합니다 |
owl workspace profile use <profile_name> |
API Key 모드: 지정한 워크스페이스 항목의 Endpoint/Key를 선택한 설정에 기록하며 최상위 Profile 선택은 변경하지 않습니다 |
owl workspace same-org list |
동일 조직 내 워크스페이스를 나열합니다(아래 참조) |
workspace명령은 별칭workspaces로도 작성할 수 있습니다.
액세스 토큰을 설정할 때 api-key와 token 두 키 이름은 동일하며, 어느 하나에 기록해도 같은 액세스 토큰으로 업데이트됩니다. 워크스페이스 수준 토큰도 동일한 동등 규칙을 따릅니다.
owl workspace same-org list¶
현재 계정과 동일 조직(same-org)인 워크스페이스를 나열합니다. 지원되는 플래그:
| 플래그 | 설명 |
|---|---|
--page-size <n> |
페이지당 항목 수, 값 범위 1-100, 기본값 20; 범위를 벗어나면 오류가 발생합니다 |
--before-id <id> |
페이지네이션 커서, id가 이 값보다 작은 워크스페이스만 반환합니다. 커서 값은 서버에서 반환되며 배열 인덱스로 추정할 수 없습니다 |
--uuid <uuid> |
workspace_uuid로 필터링하며 여러 번 반복 전달할 수 있습니다 |
--all |
서버에서 반환된 커서를 따라 자동으로 페이지를 넘겨 모든 페이지를 반환합니다 |
페이지네이션 규칙:
- 기본적으로 한 페이지만 반환합니다. 더 많은 결과가 있으면 텍스트 출력에
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
Profile을 선택하지 않은 이전 설정 모드이거나 사용 중단된 --conf를 사용하는 경우에만 OWL_REGISTRY_ENDPOINT, OWL_API_KEY, OWL_TOKEN이 설정 파일보다 우선합니다. OWL_API_KEY는 OWL_TOKEN보다 우선합니다. Profile을 선택한 후에는 Endpoint/Key 전체가 해당 Profile에서 제공됩니다.
카테고리 및 도구 카탈로그¶
카테고리와 도구를 조회하기 전에 먼저 동기화를 실행하는 것이 좋습니다:
카테고리 및 도구 조회 명령:
| 명령 | 설명 |
|---|---|
owl category list |
모든 카테고리를 조회합니다 |
owl category show <카테고리 ID> |
카테고리 상세 및 카테고리 내 도구를 조회합니다 |
owl list |
모든 도구를 조회합니다 |
owl list -c <카테고리 ID> |
특정 카테고리의 도구를 조회합니다 |
owl show <도구명> |
도구 상세 및 파라미터 정의를 조회합니다 |
owl validate <도구명> [파라미터] |
도구 파라미터와 도구 전용 구문을 검증하지만 도구는 실행하지 않습니다 |
owl capabilities |
CLI가 지원하는 기계 판독 가능 기능을 출력합니다 |
도구 실행¶
owl exec를 사용하여 도구를 실행합니다.
도구 이름은 owl list에 표시된 이름과 일치해야 합니다. 실행 전에 owl show <도구명>으로 파라미터 정의를 확인할 수 있습니다.
파라미터 전달 방식¶
owl exec는 다음 네 가지 파라미터 전달 방식을 지원합니다.
--key value 사용¶
파라미터 이름과 값을 등호로 연결하는 방식도 지원합니다. 예: owl exec owl.metric.list --mode=source --start_time=1792548000000 --end_time=1792551600000.
key=value 사용¶
-p로 JSON 전달¶
표준 입력에서 JSON 읽기¶
echo '{"mode":"source","start_time":1792548000000,"end_time":1792551600000}' | owl exec owl.metric.list --stdin
실행 규칙¶
도구 실행 시 다음에 유의합니다:
- 도구 이름은
owl list에 표시된 이름과 일치해야 합니다 - 필수 파라미터는 모두 제공해야 합니다
- 파라미터 이름은 도구 정의와 일치해야 합니다
- 파라미터 유형은 도구 정의와 일치해야 합니다
- 반환 결과의 표시 여부는
OWL_TOKEN에 대응하는 API Key 권한에 따라 달라집니다 - DQL 쿼리 반환 필드의 의미는 반환 필드 설명을 참조하세요.
예: 메트릭 소스 조회¶
owl show owl.metric.list
owl exec owl.metric.list --mode source --start_time 1792548000000 --end_time 1792551600000
예: 이벤트 목록 조회¶
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 --start_time 1792548000000 --end_time 1792551600000
owl validate owl.data.query -p '{"dql_namespace":"L","query_text":"L::re(`.*`):(count(*))","query_mode":"dql","start_time":1792548000000,"end_time":1792551600000}' -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/v1이며 사전 검증 기능 식별자는 tool.validate/v1입니다. owl tool validate, owl tools validate, owl tool capabilities 및 owl tools capabilities는 해당 네임스페이스 별칭입니다.
v1.6.0 시간 검증 및 실행 결과¶
v1.6.0은 13자리 정수 밀리초 타임스탬프를 통일적으로 검증하며 종료 시간이 시작 시간보다 커야 합니다. 쌍으로 제공해야 하는 파라미터는 한쪽만 전달할 수 없습니다. 필수 요구 사항과 최대 범위는 각 도구 스키마를 기준으로 합니다. owl.data.query의 최대 시간 범위는 7일입니다.
owl.data.query의 DQL에서는 인라인 시간 창을 생략하고 start_time / end_time으로 쿼리 창을 제공할 수 있습니다. 인라인 절대 창은 외부 창과 일치해야 하며 상대 창은 거부됩니다. PromQL 범위 선택자는 조회 기간(lookback)을 나타내며 쿼리 창으로 사용되지 않고 DQL 검증에도 들어가지 않습니다. Registry에는 사용 가능한 dqlcheck가 필요하며, 검증을 사용할 수 없으면 DQL 쿼리를 실행하지 않습니다. 요청 창은 백엔드의 실제 실행 시간 또는 결과가 포괄하는 시간 범위와 동일하지 않습니다.
owl validate는 계속 valid로 사전 검증 통과 여부를 나타내며, valid: false 자체는 종료 코드 규칙을 변경하지 않습니다. owl exec -f json의 파라미터 사전 검증이 실패하면 JSON을 출력하고 0이 아닌 상태 코드로 종료합니다. issues에 따라 파라미터를 수정한 후 다시 실행하세요.
owl sync는 어느 한 카테고리라도 다운로드에 실패하면 실패를 반환하고, 실패한 카테고리의 기존 캐시와 로컬 버전을 유지합니다. 최초 자동 동기화가 실패하면 이후 실행이 차단됩니다. 캐시 만료 후 자동 동기화가 실패하면 기존 동작대로 경고하고 이미 있는 캐시를 사용합니다.
설정 파일 및 우선순위¶
기본 설정 파일 경로:
| 운영 체제 | 설정 파일 경로 |
|---|---|
| Windows | %USERPROFILE%\.owl\config.yaml |
| Linux / macOS | $HOME/.owl/config.yaml |
설정 파일 예시:
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
Profile 선택 기능을 사용하지 않거나 사용 중단된 --conf를 단독으로 사용하는 경우 설정 우선순위는 높은 순서에서 낮은 순서로 다음과 같습니다:
- 환경 변수
--conf로 지정한 설정 파일(해당 파라미터를 설정한 경우)${OWL_DIR}/config.yaml(--conf를 설정하지 않은 경우)
Profile 선택 우선순위는 --profile > OWL_PROFILE > 영구 저장된 선택입니다. Profile이 적용되면 Endpoint/인증 정보의 환경 변수 재정의는 무시됩니다. 이전 루트 설정은 그대로 default로 사용됩니다.
registry.request_timeout은 단일 Registry HTTP 요청의 총 타임아웃을 제어하며 단위는 밀리초입니다. 기본값 150000은 데이터 쿼리 도구의 서버 측 130초 제한보다 길어 응답 인코딩 및 네트워크 전송 시간을 확보합니다. 업스트림 쿼리 소요 시간을 명확히 이해하는 경우에만 조정하세요.
캐시 및 동기화¶
owl sync는 Guance의 카테고리와 도구 메타데이터를 로컬 캐시 디렉터리에 동기화합니다.
다음 경우에는 owl sync를 다시 실행해야 합니다:
- 최초 설치 완료 후
- 플랫폼에서 새 도구를 릴리스한 경우
- 플랫폼에서 기존 도구의 파라미터 또는 설명을 업데이트한 경우
- 로컬 캐시 내용을 새로 고쳐야 하는 경우
자주 사용하는 동기화 및 캐시 명령:
| 명령 | 설명 |
|---|---|
owl sync |
모든 카테고리와 도구를 동기화합니다 |
owl sync -c <카테고리 ID> |
지정한 카테고리만 동기화합니다 |
owl cache status |
캐시 상태를 조회합니다 |
owl cache clear |
모든 캐시를 정리합니다 |
owl cache clear -c <카테고리 ID> |
지정한 카테고리의 캐시를 정리합니다 |
버전 업데이트 알림¶
설치 프로그램으로 업데이트 채널을 구성한 경우 owl exec는 최대 24시간에 한 번 새 버전을 확인합니다. 새 버전이 발견되면 JSON 결과에 notice 필드가 추가되며 기존 success, output, file 등의 필드는 변경되지 않습니다. 확인 실패는 도구 실행을 차단하지 않습니다.
다음 명령을 실행하여 현재 업데이트 채널에 따라 업그레이드할 수 있습니다:
자동 확인을 끄려면 설정 파일에서 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에 전달해야 합니다.
자주 사용하는 데이터 파일 명령:
| 명령 | 설명 |
|---|---|
owl data list |
데이터 파일 목록을 조회합니다 |
owl data show <file-id> |
지정한 데이터 파일의 상세 정보를 조회합니다 |
owl data rm <file-id> |
지정한 데이터 파일을 삭제합니다 |
owl data clean --days <일수> |
지정한 일수보다 오래된 파일을 정리합니다 |
owl data stats |
데이터 파일 통계 정보를 조회합니다 |
Agent 대상 스키마 출력¶
OWL CLI를 사용자 정의 Agent에 연결해야 하는 경우 함수 호출 스키마를 내보낼 수 있습니다:
지정한 카테고리만 내보내기:
owl schema의 출력에는 다음이 포함됩니다:
owl_exec: 모든 OWL 도구를 통합 실행합니다owl_list_categories: 카테고리를 나열합니다owl_list_tools: 도구를 나열합니다- 현재 동기화된 도구 정의
Agent에 연결하기 전에 먼저 owl sync를 실행하여 로컬 스키마가 플랫폼의 현재 도구 카탈로그와 일치하도록 하는 것이 좋습니다.
대상 클라이언트가 MCP를 지원하는 경우 MCP Server 빠른 시작의 원격 MCP Server 연결 방식을 우선 사용하세요.
도움말 명령¶
OWL CLI 도움말 조회:
지정한 명령의 도움말 조회: