### Example: Query metric sources

Source: https://docs.guance.com/owl/cli-reference/

Shows the tool definition and executes the tool with --mode source.

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

--------------------------------

### Example: Query event list

Source: https://docs.guance.com/owl/cli-reference/

Shows the tool definition and executes the tool with start_time, end_time, and limit parameters.

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

--------------------------------

### View help for specific OWL CLI commands

Source: https://docs.guance.com/owl/cli-reference/

Use `owl help <command>` to view help for a specific command. Examples include `exec`, `sync`, and `data`.

```bash
owl help exec
owl help sync
owl help data
```

--------------------------------

### Example configuration file for Owl CLI

Source: https://docs.guance.com/owl/cli-reference/

Sample YAML configuration file for the Owl CLI. It sets registry endpoint, authentication token, cache and data directories, sync settings, execution timeouts, and logging. The `registry.request_timeout` controls the total timeout for a single Registry HTTP request in milliseconds; the default 150000 is higher than the 130-second server-side limit for data query tools.

```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
```

--------------------------------

### List data files with owl data list

Source: https://docs.guance.com/owl/cli-reference/

Run `owl data list` to view the list of data files. Use `-f json` to get authoritative file IDs.

```bash
owl data list
```

--------------------------------

### owl.data.search_dql_docs

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

Searches locally synchronized DQL documentation and example snippets. This is a local helper operation.

```APIDOC
## owl.data.search_dql_docs

### Description
Searches locally synchronized DQL documentation and example snippets. This is a local helper operation.

### Method
CLI tool

### Endpoint
owl.data.search_dql_docs

### Parameters
#### Query Parameters
- **query** (string) - Required - The search query.
- **refresh_docs** (boolean) - Optional - Whether to refresh the local docs.
- **limit** (integer) - Optional - Maximum number of results.

### Response
#### Success Response
- **results** (array) - List of matching documentation snippets.

#### Response Example
```json
{
  "results": [
    {
      "title": "percentile",
      "snippet": "..."
    }
  ]
}
```
```

--------------------------------

### owl.infrastructure.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets details of an infrastructure object. Used after identifying the object via list.

```APIDOC
## owl.infrastructure.get

### Description
Gets details of an infrastructure object.

### Parameters
- **identifier** (string) - Required - Identifier of the object.

### Permissions
Read-only

```

--------------------------------

### owl.monitor.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets monitor details by rule_uuid. Used to view a specific monitor.

```APIDOC
## owl.monitor.get

### Description
Gets monitor details by rule_uuid.

### Parameters
- **rule_uuid** (string) - Required - UUID of the monitor rule.

### Permissions
Read-only

```

--------------------------------

### owl.dashboard.get

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

Gets the current configuration of a dashboard. Used for viewing dashboard configuration.

```APIDOC
## owl.dashboard.get

### Description
Gets the current configuration of a dashboard.

### Parameters
- **dashboard_id** (string) - Required - ID of the dashboard.

### Permissions
Read-only

```

--------------------------------

### owl.dashboard.create

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

Creates a dashboard. For example, create a dashboard named 'APM Overview'. This is a write operation.

```APIDOC
## owl.dashboard.create

### Description
Creates a dashboard.

### Parameters
- **name** - Required - The name of the dashboard.
- **dashboard_json** - Required - The dashboard configuration in JSON format.

### Permissions
Write
```

--------------------------------

### owl.field_schema.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets field catalog information. Used to discover field schemas.

```APIDOC
## owl.field_schema.get

### Description
Gets field catalog information.

### Parameters
None specified in source.

### Permissions
Read-only

```

--------------------------------

### owl.catalog.entity_get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets details of a single entity by its URN.

```APIDOC
## owl.catalog.entity_get

### Description
Gets details of a single entity by its URN.

### Parameters
- **urn** (string) - Required - The URN of the entity.

### Response
Returns the entity details.
```

--------------------------------

### owl.dashboard.get

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

Gets the details of a dashboard by its UUID. This is a read-only operation.

```APIDOC
## owl.dashboard.get

### Description
Gets the details of a dashboard by its UUID.

### Parameters
- **dashboard_uuid** - Required - The UUID of the dashboard.

### Permissions
Read-only
```

--------------------------------

### 写入本地配置文件（owl init 和 owl login）

Source: https://docs.guance.com/owl/quickstart-cli/

使用 owl init 写入 OWL CLI Endpoint，使用 owl login 写入访问令牌。未选择 Profile 时，本地配置写入 ${OWL_DIR}/config.yaml，默认是 ~/.owl/config.yaml。选中 Profile 后，init 和 login 写回所选配置。

```bash
owl init
owl login
```

--------------------------------

### owl.incident.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets an incident by UUID. Used when the incident UUID is known.

```APIDOC
## owl.incident.get

### Description
Gets an incident by UUID.

### Parameters
- **uuid** (string) - Required - UUID of the incident.

### Permissions
Read-only

```

--------------------------------

### owl.logging.cluster_task.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets the result of a log clustering analysis task by task_id.

```APIDOC
## owl.logging.cluster_task.get

### Description
Gets the result of a log clustering analysis task by task_id.

### Parameters
- **task_id** (string) - Required - The ID of the clustering task.

### Response
Returns the clustering analysis result.
```

--------------------------------

### View OWL CLI general help

Source: https://docs.guance.com/owl/cli-reference/

Use `owl --help` to display general help information for the OWL CLI.

```bash
owl --help
```

--------------------------------

### Windows 离线安装 OWL CLI

Source: https://docs.guance.com/owl/install-owl/

在 Windows 上使用 install.ps1 脚本进行离线安装。需要指定 -LocalPackage、-RegistryEndpoint、-Token 和 -Yes 参数。

```powershell
powershell .\install.ps1 `
  -LocalPackage `
  -RegistryEndpoint "https://owl-api.guance.com" `
  -Token "your-token" `
  -Yes
```

--------------------------------

### CLI 跨空间数据查询

Source: https://docs.guance.com/owl/cross-workspace-query/

使用 owl.data.simple_query_file 查询指定空间和站点的数据，时间戳为毫秒。

```bash
owl exec owl.data.simple_query_file -p '{"namespace":"L","source":"nginx","start_time":1772516130000,"end_time":1772516140000,"limit":100,"workspace_uuids":["wksp_b","wksp_c"],"target_region":"cn2"}'
```

--------------------------------

### 初始化与配置命令

Source: https://docs.guance.com/owl/cli-reference/

用于初始化 OWL CLI、登录、查看和设置配置。

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

--------------------------------

### Linux/macOS 离线安装 OWL CLI

Source: https://docs.guance.com/owl/install-owl/

在 Linux 或 macOS 上使用 install.sh 脚本进行离线安装。需要先赋予脚本执行权限，并指定 --local-package、--registry-endpoint、--token 和 --yes 参数。

```bash
chmod +x ./install.sh
./install.sh \
  --local-package \
  --registry-endpoint "https://owl-api.guance.com" \
  --token "your-token" \
  --yes
```

--------------------------------

### owl.catalog.entity_query

Source: https://docs.guance.com/owl/mcp-tools-reference/

Queries a list of entities by entity type. For example, query all host entities.

```APIDOC
## owl.catalog.entity_query

### Description
Queries a list of entities by entity type. For example, query all host entities.

### Parameters
- **entity_type** (string) - Required - The entity type to query.
- **page_size** (integer) - Optional - Number of results per page.
- **page_index** (integer) - Optional - Page index for pagination.

### Response
Returns a list of entities of the specified type.
```

--------------------------------

### 检查安装：owl --help 和 owl config show

Source: https://docs.guance.com/owl/install-owl/

安装完成后，重新打开终端，执行这些命令以确认本地可执行文件和配置文件已就绪。如果命令正常输出帮助信息和当前配置，则安装成功。

```bash
owl --help
owl config show
```

--------------------------------

### 新增和切换 Profile 的命令

Source: https://docs.guance.com/owl/profiles/

使用 `owl profile add` 交互输入 Endpoint、API Key 和可选空间信息，`--from` 复制已有配置。`owl switch` 切换默认 Profile，`owl profile current` 查看当前选择。新增 Profile 只保存配置，不切换当前选择；同名会报错。

```bash
# 交互输入 Endpoint、API Key，以及可选的空间 UUID 和名称
owl profile add customer-a

# 复制已有配置；后续修改不会影响源文件
owl profile add customer-b --from ./customer-b.yaml

owl profile list
owl switch customer-a
owl profile current
owl exec owl.metric.list --mode source
```

--------------------------------

### same-org 工作空间列表命令

Source: https://docs.guance.com/owl/cli-reference/

列出同组织的工作空间，支持分页、过滤和自动翻页。

```bash
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.event.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Gets event content by event reference. Used to retrieve event details after listing incident events.

```APIDOC
## owl.event.get

### Description
Gets event content by event reference.

### Parameters
- **event_id** (string) - Required - ID of the event.

### Permissions
Read-only

```

--------------------------------

### 执行工具（owl exec）

Source: https://docs.guance.com/owl/quickstart-cli/

执行 owl.data.show_dql_namespace 命令，查看当前工作空间支持的 DQL 命名空间。这是使用 owl.data.query 前的第一步。

```bash
owl exec owl.data.show_dql_namespace
```

--------------------------------

### 独立文件与旧配置的目录结构

Source: https://docs.guance.com/owl/profiles/

默认存储在 `~/.owl`，设置 `OWL_DIR` 时跟随该目录。`state.yaml` 记录别名、稳定的目录标识及当前默认，不包含 Key。

```text
~/.owl/
├── config.yaml
├── state.yaml
└── profiles/
    └── profile-<id>/
        ├── config.yaml
        ├── cache/
        ├── data/
        └── logs/
```

--------------------------------

### 升级与同步工具目录

Source: https://docs.guance.com/owl/cross-workspace-query/

升级 CLI 至 v1.4.0 后执行全量同步，并列出 workspace 分类工具。

```bash
owl sync
owl tool list --category workspace
```

--------------------------------

### Verification question: list available metric sources

Source: https://docs.guance.com/owl/mcp-quickstart/

Ask this question in an MCP client after configuring OWL MCP Server. In facade mode, the client should discover list_catalogs, list_tools, and exec_tool, and can call owl.metric.list via exec_tool; in static mode, the client directly discovers owl.metric.list and other business tools. If the server has an exclusion list configured, some tools will not appear.

```text
列出当前可用的指标 source。
```

--------------------------------

### 使用环境变量配置 Endpoint 和访问令牌（bash/zsh）

Source: https://docs.guance.com/owl/quickstart-cli/

在 bash 或 zsh 终端中设置环境变量 OWL_REGISTRY_ENDPOINT 和 OWL_TOKEN。环境变量只在当前终端会话中生效，关闭终端后需重新设置。OWL_REGISTRY_ENDPOINT 只填写 Endpoint 根地址，不要拼接 /api/v1 或其他路径。

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

--------------------------------

### Sync tools and list available tools

Source: https://docs.guance.com/owl/troubleshooting/

Run `owl sync` to refresh the local tool cache, then `owl list` to display available tools. This resolves 'tool not found' errors caused by missing cache or incorrect tool names.

```bash
owl sync
owl list
```

--------------------------------

### 创建首批查询任务：owl exec owl.data_forwarding.query.create

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

调用此命令创建数据转发查询任务，需原样传入选中的 rule_name、查询时间范围和过滤条件，取得 task_id。start_time 和 end_time 为 13 位毫秒时间戳，end_time 必须大于 start_time。

```bash
owl exec owl.data_forwarding.query.create -p '{
  "rule_name": "forward-rule",
  "start_time": 1784800000000,
  "end_time": 1784886400000,
  "search": {
    "conditions": [
      {
        "key": "status",
        "value": "error",
        "logic": "match"
      }
    ],
    "operator": "and"
  },
  "page_size": 20
}'
```

--------------------------------

### 取消 OWL_PROFILE 后切换

Source: https://docs.guance.com/owl/profiles/

如果设置了 `OWL_PROFILE`，必须先取消它才能执行 `owl switch`；`switch` 也不接受 `--profile` 或 `--conf`。

```bash
unset OWL_PROFILE
owl switch customer-b
```

--------------------------------

### Profile 管理命令

Source: https://docs.guance.com/owl/cli-reference/

用于添加、列出、切换和查看 Profile，支持从文件导入配置。

```bash
owl profile add customer-a
owl profile add customer-b --from ./customer-b.yaml
owl profile list
owl switch customer-a
owl --profile customer-b exec owl.data.show_dql_namespace
owl profile current -f json
```

--------------------------------

### 验证连通性：owl sync

Source: https://docs.guance.com/owl/install-owl/

执行 owl sync 以验证当前终端与 OWL CLI Endpoint 的连通性。如果命令正常完成，说明可以访问 Endpoint 且 OWL_TOKEN 可用于同步工具目录。若返回认证、权限或网络错误，请参考故障排查文档。

```bash
owl sync
```

--------------------------------

### 查询下一批数据：复用参数并传入 next_token

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

当 task_status 为 completed 且 next_token 非空时，再次调用 create 查询下一批。必须保留原来的 rule_name、start_time、end_time、search 和 page_size，并将 next_token 作为 token 传入。

```bash
owl exec owl.data_forwarding.query.create -p '{
  "rule_name": "forward-rule",
  "start_time": 1784800000000,
  "end_time": 1784886400000,
  "search": {
    "conditions": [
      {
        "key": "status",
        "value": "error",
        "logic": "match"
      }
    ],
    "operator": "and"
  },
  "page_size": 20,
  "token": "next_xxx"
}'
```

--------------------------------

### View data file statistics with owl data stats

Source: https://docs.guance.com/owl/cli-reference/

Run `owl data stats` to view statistics about data files.

```bash
owl data stats
```

--------------------------------

### Show tool definition with owl show

Source: https://docs.guance.com/owl/troubleshooting/

Displays the definition of a tool, including its required parameters. Use this to resolve 'missing required parameter' errors by identifying and supplying the missing parameters.

```bash
owl show <工具名>
```

--------------------------------

### 临时选择和脚本使用

Source: https://docs.guance.com/owl/profiles/

使用 `--profile` 或 `OWL_PROFILE` 临时选择 Profile，不会修改持久化默认。选择顺序为 `--profile` > `OWL_PROFILE` > `owl switch` 保存的默认。`-f json` 输出可直接解析。

```bash
owl --profile customer-b exec owl.metric.list --mode source
OWL_PROFILE=customer-b owl exec owl.metric.list --mode source

owl profile list -f json
owl --profile customer-b profile current -f json
```

--------------------------------

### 常用 CLI 命令示例

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

展示 OWL CLI 的常用命令，包括同步工具目录、列出工具、按分类浏览、查看工具定义以及执行数据查询和事件查询。这些命令是使用 OWL CLI 的基础操作。

```bash
owl sync
owl list
owl list -c data
owl show owl.data.query
owl exec owl.metric.list --mode source
owl exec owl.event.list --start_time 1712505600000 --end_time 1712592000000 --limit 20
```

--------------------------------

### 发现授权空间

Source: https://docs.guance.com/owl/cross-workspace-query/

调用 owl.workspace.data_authorized.list 列出授权空间，空参数返回所有站点。

```bash
owl exec owl.workspace.data_authorized.list -p '{}'
```

--------------------------------

### Show data file details with owl data show

Source: https://docs.guance.com/owl/cli-reference/

Run `owl data show <file-id>` to view details of a specific data file. Replace `<file-id>` with the actual file ID.

```bash
owl data show <file-id>
```

--------------------------------

### Execute a tool with owl exec

Source: https://docs.guance.com/owl/cli-reference/

Basic syntax for executing a tool. The tool name must match exactly as shown in owl list.

```bash
owl exec <工具名> [参数]
```

--------------------------------

### 调用成员工具及兼容旧脚本

Source: https://docs.guance.com/owl/cross-workspace-query/

使用新工具名 owl.workspace.member.list 和旧别名 owl.member.list 查询成员，参数相同。

```bash
owl exec owl.workspace.member.list -p '{"search":"alice"}'
# 兼容旧脚本
owl exec owl.member.list -p '{"search":"alice"}'
```

--------------------------------

### List categories and tools

Source: https://docs.guance.com/owl/cli-reference/

Commands to view all categories, category details, all tools, tools in a category, and tool details.

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

--------------------------------

### 修改、重命名与删除 Profile

Source: https://docs.guance.com/owl/profiles/

使用 `login`、`config set`、`workspace use` 修改所选 Profile，不改变持久化选择。`profile rename` 重命名，`profile remove` 删除，`--purge` 同时删除缓存和查询文件。

```bash
owl --profile customer-a login
owl --profile customer-a config set registry.request_timeout 180000
owl --profile customer-a workspace use wksp_example

owl profile rename customer-a customer-a-prod
owl profile remove customer-b

# 仅在需要同时删除该 Profile 的缓存和查询文件时使用
owl profile remove obsolete-profile --purge
```

--------------------------------

### 同组织跨工作空间 Trace 查询：列出空间并执行查询

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

需要查询其他同组织空间且 UUID 未确定时，先运行 owl workspace same-org list 获取候选空间，再使用 workspace_uuid 调用 owl.data.same_org.trace.query。trace_id 为必填参数，workspace_uuids 省略时只查询当前工作空间。

```bash
owl workspace same-org list
owl exec owl.data.same_org.trace.query -p '{"trace_id":"TRACE-XXXX","workspace_uuids":["wksp_xxx"]}'
```

--------------------------------

### 发现可查询规则：owl exec owl.data_forwarding.rule.list

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

当用户没有提供准确规则名或规则是否可查询尚未确认时，先调用此命令。查询场景保持 queryable_only=true，从 queryable=true 的结果中选择 rule_name，不要把 rule_uuid 传给 create。

```bash
owl exec owl.data_forwarding.rule.list -p '{
  "queryable_only": true,
  "page_index": 1,
  "page_size": 20
}'
```

--------------------------------

### Bash 补全：永久启用（写入静态补全文件）

Source: https://docs.guance.com/owl/cli-reference/

将补全脚本保存到 ~/.local/share/bash-completion/completions/owl 并加载，适用于 bash-completion 自动加载该目录的场景。更新 OWL 后需重新生成。

```bash
mkdir -p ~/.local/share/bash-completion/completions
owl completion bash > ~/.local/share/bash-completion/completions/owl
source ~/.local/share/bash-completion/completions/owl
```

--------------------------------

### 从已弃用的 --conf 迁移

Source: https://docs.guance.com/owl/profiles/

CLI 的 `--conf` 已弃用，从帮助中隐藏；兼容期保留原行为，使用时向 stderr 输出一次迁移提示，不影响 JSON stdout。建议将配置导入后使用别名。

```bash
owl profile add standalone --from ./standalone.yaml
owl --profile standalone config show
```

--------------------------------

### 单次命令临时选择 Profile（--profile）

Source: https://docs.guance.com/owl/quickstart-cli/

使用 --profile 参数在单次命令中临时选择另一份配置，不改变默认选择。选择优先级为 --profile > OWL_PROFILE > 持久化选择。

```bash
owl --profile customer-b sync
owl --profile customer-b exec owl.data.show_dql_namespace -f json
```

--------------------------------

### MCP 跨空间数据查询

Source: https://docs.guance.com/owl/cross-workspace-query/

facade 模式通过 exec_tool 调用 owl.data.simple_query，参数与 CLI 示例相同。

```json
{
  "tool_name": "owl.data.simple_query",
  "parameters": {
    "namespace": "L",
    "source": "nginx",
    "start_time": 1772516130000,
    "end_time": 1772516140000,
    "workspace_uuids": ["wksp_b", "wksp_c"],
    "target_region": "cn2"
  }
}
```

--------------------------------

### Inspect active profile and configuration

Source: https://docs.guance.com/owl/troubleshooting/

Use these commands to view the currently active profile and the effective configuration source. This helps diagnose authentication failures or endpoint access issues.

```bash
owl profile current -f json
owl config show
```

--------------------------------

### Linux/macOS 在线安装 OWL

Source: https://docs.guance.com/owl/install-owl/

使用 curl 和 bash 执行在线安装脚本，需设置环境变量 OWL_INSTALL_BASE_URL、OWL_REGISTRY_ENDPOINT 和 OWL_TOKEN。执行前需确保系统已安装 bash、curl 和 tar。

```bash
OWL_INSTALL_BASE_URL="https://static.guance.com/owl" \
OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com" \
OWL_TOKEN="your-token" \
bash -c "$(curl -fsSL https://static.guance.com/owl/install.sh)" -- --yes
```

--------------------------------

### 完整示例（bash/zsh）

Source: https://docs.guance.com/owl/quickstart-cli/

从配置环境变量到执行工具的完整流程，适用于 bash/zsh 终端。

```bash
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
```

--------------------------------

### 升级 OWL CLI：owl update

Source: https://docs.guance.com/owl/install-owl/

已配置更新通道时，执行此命令升级。owl update 沿用本机 update.base_url 指定的通道，普通版本只升不降，同版本保留二进制。升级到 v1.4.0 后执行 owl sync 全量刷新工具目录。

```bash
owl update
```

--------------------------------

### owl.data_forwarding.query.create

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

创建数据转发查询任务。需要传入 rule_name、start_time、end_time、search、page_size 等参数，返回 task_id。支持分页查询，通过 token 参数传入 next_token 获取下一批数据。

```APIDOC
## owl.data_forwarding.query.create

### Description
创建数据转发查询任务。需要传入 rule_name、start_time、end_time、search、page_size 等参数，返回 task_id。支持分页查询，通过 token 参数传入 next_token 获取下一批数据。

### Method
CLI 工具调用

### Endpoint
`owl exec owl.data_forwarding.query.create`

### Parameters
#### Request Body
- **rule_name** (string) - Required - 规则名称，必须使用 rule.list 返回的准确值，不能使用 rule_uuid。
- **start_time** (integer) - Required - 13 位毫秒时间戳。
- **end_time** (integer) - Required - 13 位毫秒时间戳，必须大于 start_time。
- **search** (object) - Optional - 过滤条件，包含 conditions 和 operator。
  - **conditions** (array) - Optional - 条件列表，每个条件包含 key、value、logic。
    - **key** (string) - Required - 字段名。
    - **value** (string) - Required - 字段值。
    - **logic** (string) - Required - 支持 match 和 notMatch。
  - **operator** (string) - Optional - 多个条件的组合方式，支持 and 或 or。
- **page_size** (integer) - Optional - 每页大小，1 到 1000，默认 20。
- **token** (string) - Optional - 分页令牌，用于查询下一批数据，传入上一批返回的 next_token。

### Request Example
```json
{
  "rule_name": "forward-rule",
  "start_time": 1784800000000,
  "end_time": 1784886400000,
  "search": {
    "conditions": [
      {
        "key": "status",
        "value": "error",
        "logic": "match"
      }
    ],
    "operator": "and"
  },
  "page_size": 20
}
```

### Response
#### Success Response
返回 task_id 和 query_time_limit_hours（当前实际生效的查询时长上限）。

#### Response Example
```json
{
  "task_id": "task_xxx",
  "query_time_limit_hours": 24
}
```
```

--------------------------------

### 查询任务状态和结果：query.get 与数据文件查看

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

使用 task_id 调用 query.get 查询任务状态，但返回的文件信息不包含 ID。需运行 owl data list -f json 找到对应条目，原样保存 files[].id，再执行 owl data show <file-id> 查看任务状态和脱敏结果。

```bash
owl exec owl.data_forwarding.query.get -p '{"task_id":"task_xxx"}'
owl data list -f json
owl data show <保存的文件-ID>
```

--------------------------------

### owl.nbook_note.add

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

创建普通笔记或 Runbook 并返回基础信息。

```APIDOC
## owl.nbook_note.add

### Description
创建普通笔记或 Runbook 并返回基础信息。

### Method
add

### Parameters
#### Request Body
- **title** (string) - Required - 笔记或 Runbook 的标题。
- **content** (string) - Required - Markdown 正文。
- **tags** (array) - Optional - 标签列表。
- **tag_kv** (object) - Optional - 键值对象。
- **type** (string) - Optional - 可选值为 `normal` 和 `runbook`，省略时创建普通笔记。

### Response
#### Success Response
- 返回创建后的基础信息，不包含 Markdown 正文。

```

--------------------------------

### 使用环境变量配置 Endpoint 和访问令牌（PowerShell）

Source: https://docs.guance.com/owl/quickstart-cli/

在 PowerShell 终端中设置环境变量 OWL_REGISTRY_ENDPOINT 和 OWL_TOKEN。环境变量只在当前终端会话中生效，关闭终端后需重新设置。OWL_REGISTRY_ENDPOINT 只填写 Endpoint 根地址，不要拼接 /api/v1 或其他路径。

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

--------------------------------

### Sync tools and list categories

Source: https://docs.guance.com/owl/troubleshooting/

Run `owl sync` to refresh the local cache, then `owl category list` to display available categories. This resolves 'category not found' errors.

```bash
owl sync
owl category list
```

--------------------------------

### owl.data.simple_query_file

Source: https://docs.guance.com/owl/cross-workspace-query/

CLI 工具，用于跨空间数据查询。在现有 DQL 参数之外增加 `workspace_uuids` 和 `target_region` 参数。

```APIDOC
## owl.data.simple_query_file

### Description
CLI 工具，用于跨空间数据查询。在现有 DQL 参数之外增加 `workspace_uuids` 和 `target_region` 参数。

### Method
CLI 工具调用

### Endpoint
`owl exec owl.data.simple_query_file -p '{"参数":"值"}'`

### Parameters
#### Query Parameters
- **namespace** (string) - Required - 数据命名空间。
- **source** (string) - Required - 数据源。
- **start_time** (integer) - Required - 开始时间，13 位毫秒时间戳。
- **end_time** (integer) - Required - 结束时间，13 位毫秒时间戳，晚于开始时间，跨度最多 7 天。
- **limit** (integer) - Optional - 返回数据条数。
- **workspace_uuids** (string[]) - Optional - 非空数组，元素取自授权空间列表的 `workspace_uuid`。
- **target_region** (string) - Optional - 取自列表的 `region_code`；提供此参数时必须同时提供 `workspace_uuids`。

### Request Example
```json
{
  "namespace": "L",
  "source": "nginx",
  "start_time": 1772516130000,
  "end_time": 1772516140000,
  "limit": 100,
  "workspace_uuids": ["wksp_b", "wksp_c"],
  "target_region": "cn2"
}
```

### Response
#### Success Response
- 查询结果保存为 data 文件，并在文件索引的参数中保留空间和站点范围。

#### Response Example
```json
{
  "success": true,
  "data": {
    "page_info": {"has_more": false},
    "data": []
  }
}
```
```

--------------------------------

### 执行工具并指定 JSON 格式（owl exec -f json）

Source: https://docs.guance.com/owl/quickstart-cli/

执行 owl.data.show_dql_namespace 命令并指定 JSON 格式输出，适合机器可读。

```bash
owl exec owl.data.show_dql_namespace -f json
```

--------------------------------

### 查看工具参数说明（owl show owl.data.query）

Source: https://docs.guance.com/owl/quickstart-cli/

查看指定工具的参数说明。

```bash
owl show owl.data.query
```

--------------------------------

### owl.nbook_note.list

Source: https://docs.guance.com/owl/owl-cli-tools-reference/

查询可见的笔记与 Runbook 基础信息，不返回 Markdown 正文。支持按类型、标题、正文或标签筛选内容。

```APIDOC
## owl.nbook_note.list

### Description
查询可见的笔记与 Runbook 基础信息，不返回 Markdown 正文。

### Method
list

### Parameters
#### Query Parameters
- **page_index** (integer) - Optional - 页码，默认值为 1。
- **page_size** (integer) - Optional - 每页大小，默认值为 20，最大值为 100。
- **search** (string) - Optional - 按标题、正文或标签筛选内容。
- **tags** (array) - Optional - 按标签筛选。
- **tagkv_query** (string) - Optional - TagKV 表达式字符串。
- **type** (string) - Optional - 可选值为 `normal` 和 `runbook`；省略时返回两种类型。

### Response
#### Success Response
- 返回笔记与 Runbook 的基础信息列表，不包含 Markdown 正文。

```

--------------------------------

### 命令行补全示例

Source: https://docs.guance.com/owl/profiles/

启用 Bash 或 PowerShell 补全后，可用 Tab 提示本地 Profile 别名。补全只读本地配置，不切换 Profile、不联网。

```bash
owl switch customer-<Tab>
owl profile rename customer-<Tab>
owl profile remove customer-<Tab>
owl --profile customer-<Tab>
owl exec --profile=customer-<Tab>
```

--------------------------------

### Clear all cache with owl cache clear

Source: https://docs.guance.com/owl/cli-reference/

Run `owl cache clear` to clear the entire local cache.

```bash
owl cache clear
```

--------------------------------

### owl.monitor.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Queries details of a monitor.

```APIDOC
## owl.monitor.get

### Description
Queries details of a monitor.

### Method
MCP Tool

### Endpoint
owl.monitor.get

### Parameters
- **rule_uuid** (string) - Required - UUID of the monitor rule.

### Permissions
Read-only
```

--------------------------------

### Bash 补全：当前终端启用

Source: https://docs.guance.com/owl/cli-reference/

在当前终端启用 OWL 补全。使用 eval 加载 OWL 生成的脚本，避免部分 macOS Bash 3.2 环境中 source <(...) 静默不加载的问题。

```bash
eval "$(owl completion bash)"
```

--------------------------------

### 补全示例

Source: https://docs.guance.com/owl/cli-reference/

展示按 Tab 键时 OWL 补全的行为，包括工具名、参数名和参数值补全。

```bash
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
```

--------------------------------

### 自动安装 OWL 的 AI 指令

Source: https://docs.guance.com/owl/auto-install/

将以下内容复制到 AI 工具的对话窗口中执行。复制前需替换 <OWL_REGISTRY_ENDPOINT> 为工作空间所属站点对应的 OWL CLI Endpoint，替换 <YOUR_TEMP_CODE> 为观测云控制台生成的临时授权码。

```text
阅读 https://static.guance.com/owl/skill.md ，按照文档在当前环境中安装并配置 OWL CLI 和 OWL Skill。

安装参数如下：
OWL_REGISTRY_ENDPOINT="<OWL_REGISTRY_ENDPOINT>"
OWL_TEMP_CODE="<YOUR_TEMP_CODE>"
```

--------------------------------

### 查看分类下的工具（owl list -c data）

Source: https://docs.guance.com/owl/quickstart-cli/

查看 data 分类下的工具。

```bash
owl list -c data
```

--------------------------------

### Sync a specific category with owl sync -c

Source: https://docs.guance.com/owl/cli-reference/

Run `owl sync -c <分类ID>` to synchronize only the specified category. Replace `<分类ID>` with the actual category ID.

```bash
owl sync -c <分类ID>
```

--------------------------------

### Clean old data files with owl data clean

Source: https://docs.guance.com/owl/cli-reference/

Run `owl data clean --days <天数>` to clean historical files older than the specified number of days. Replace `<天数>` with the number of days.

```bash
owl data clean --days <天数>
```

--------------------------------

### owl.llm.list

Source: https://docs.guance.com/owl/mcp-tools-reference/

Queries a list of LLM applications for observability.

```APIDOC
## owl.llm.list

### Description
Queries a list of LLM applications.

### Method
MCP Tool

### Endpoint
owl.llm.list

### Parameters
- **search** (string) - Optional - Search keyword.
- **type** (string) - Optional - Application type filter.
- **page_size** (integer) - Optional - Number of results per page.
- **page_index** (integer) - Optional - Page index.
- **start_time** (string) - Optional - Start time for the query range.
- **end_time** (string) - Optional - End time for the query range.

### Permissions
Read-only
```

--------------------------------

### owl.infrastructure.list

Source: https://docs.guance.com/owl/mcp-tools-reference/

Lists infrastructure objects (hosts, containers, processes). Used to find target objects.

```APIDOC
## owl.infrastructure.list

### Description
Lists infrastructure objects (hosts, containers, processes).

### Parameters
None specified in source.

### Permissions
Read-only

```

--------------------------------

### PowerShell 补全：当前终端启用

Source: https://docs.guance.com/owl/cli-reference/

在当前终端启用 OWL 补全。适用于 Windows PowerShell 5.1 和 PowerShell 7。

```powershell
owl completion powershell | Out-String | Invoke-Expression
```

--------------------------------

### Linux/macOS 指定版本安装 OWL

Source: https://docs.guance.com/owl/install-owl/

在安装命令中通过 --version 参数指定版本号，例如 1.3.0。

```bash
OWL_INSTALL_BASE_URL="https://static.guance.com/owl" \
OWL_REGISTRY_ENDPOINT="https://owl-api.guance.com" \
OWL_TOKEN="your-token" \
bash -c "$(curl -fsSL https://static.guance.com/owl/install.sh)" -- --version "1.3.0" --yes
```

--------------------------------

### owl-diagnostics skill 地址

Source: https://docs.guance.com/owl/install-owl/

为 Agent 安装配套 skill 时，需要使用的 GitHub 地址。该 skill 依赖本机已安装且可执行的 owl 命令。

```text
https://github.com/GuanceCloud/ai-skills/tree/main/owl-diagnostics
```

--------------------------------

### owl.nbook_note.add

Source: https://docs.guance.com/owl/mcp-tools-reference/

Creates a new note and returns the note summary. Requires title and content, and supports tags, tag_kv, and type.

```APIDOC
## owl.nbook_note.add

### Description
Creates a new note and returns the note summary. Requires 'title' and 'content'.

### Method
MCP Tool

### Endpoint
owl.nbook_note.add

### Parameters
#### Request Body
- **title** (string) - Required - The title of the note.
- **content** (string) - Required - The Markdown content of the note.
- **tags** (array) - Optional - Tags for the note.
- **tag_kv** (object) - Optional - Key-value object for tags.
- **type** (string) - Optional - Note type, supports 'normal' and 'runbook'. Defaults to 'normal' if omitted.

### Response
#### Success Response
Returns the note summary. Does not include 'content', 'path', 'etag', or 'version'.

### Notes
- 'created_source' is set to 'ai' by the server; creation account is from the current API Key.
- Do not pass 'path' or other backend-managed fields.
```

--------------------------------

### owl.infrastructure.list

Source: https://docs.guance.com/owl/mcp-tools-reference/

Queries a list of infrastructure objects such as hosts, containers, and processes.

```APIDOC
## owl.infrastructure.list

### Description
Queries a list of infrastructure objects (e.g., hosts, containers, processes).

### Method
MCP Tool

### Endpoint
owl.infrastructure.list

### Parameters
- **resource_type** (string) - Required - The type of infrastructure resource to query.
- **limit** (integer) - Optional - Maximum number of results to return.
- **filters** (object) - Optional - Filter criteria for the query.
- **start_time** (string) - Optional - Start time for the query range.
- **end_time** (string) - Optional - End time for the query range.

### Permissions
Read-only
```

--------------------------------

### 关闭证书校验

Source: https://docs.guance.com/owl/cli-reference/

用于本地开发环境跳过 Registry HTTPS 证书校验，默认关闭，开启后存在安全风险。

```bash
owl config set registry.insecure_skip_verify true
# 或仅对当前进程生效
export OWL_REGISTRY_INSECURE_SKIP_VERIFY=true
```

--------------------------------

### owl.billing.list

Source: https://docs.guance.com/owl/mcp-tools-reference/

Discovers available sources or fields for cloud billing queries.

```APIDOC
## owl.billing.list

### Description
Discovers available sources or fields for cloud billing queries.

### Parameters
- **mode** (string) - Optional - Query mode.
- **source** (string) - Optional - The data source.
- **start_time** (integer) - Required - Start time in milliseconds.
- **end_time** (integer) - Required - End time in milliseconds.

### Response
Returns a list of available sources or fields.
```

--------------------------------

### owl.infrastructure.get

Source: https://docs.guance.com/owl/mcp-tools-reference/

Queries details of a single infrastructure object.

```APIDOC
## owl.infrastructure.get

### Description
Queries details of a single infrastructure object.

### Method
MCP Tool

### Endpoint
owl.infrastructure.get

### Parameters
- **resource_type** (string) - Required - The type of infrastructure resource.
- **identity_value** (string) - Required - The identity value of the object.
- **start_time** (string) - Optional - Start time for the query range.
- **end_time** (string) - Optional - End time for the query range.

### Permissions
Read-only
```

--------------------------------

### 查看工具分类（owl category list）

Source: https://docs.guance.com/owl/quickstart-cli/

查看所有工具分类。

```bash
owl category list
```

--------------------------------

### OpenClaw MCP configuration and verification

Source: https://docs.guance.com/owl/mcp-quickstart/

Use the openclaw mcp set command to configure OWL MCP with streamableHttp type, then verify with openclaw mcp list and openclaw mcp show owl.

```shell
openclaw mcp set owl '{
  "type": "streamableHttp",
  "url": "your-owl-mcp-endpoint",
  "headers": {
    "Authorization": "Bearer <API Key>"
  },
  "enabled": true
}'
```

```shell
openclaw mcp list
openclaw mcp show owl
```

--------------------------------

### owl.logging.list

Source: https://docs.guance.com/owl/mcp-tools-reference/

Discovers available sources or fields for logging queries.

```APIDOC
## owl.logging.list

### Description
Discovers available sources or fields for logging queries.

### Parameters
- **mode** (string) - Optional - Query mode.
- **source** (string) - Optional - The data source.
- **start_time** (integer) - Required - Start time in milliseconds.
- **end_time** (integer) - Required - End time in milliseconds.

### Response
Returns a list of available sources or fields.
```

--------------------------------

### Export function-calling schema with owl schema

Source: https://docs.guance.com/owl/cli-reference/

Run `owl schema` to export the function-calling schema for Agent integration. The output includes `owl_exec`, `owl_list_categories`, `owl_list_tools`, and currently synced tool definitions.

```bash
owl schema
```

--------------------------------

### Check cache status with owl cache status

Source: https://docs.guance.com/owl/cli-reference/

Run `owl cache status` to view the current cache status.

```bash
owl cache status
```

--------------------------------

### owl.monitor.list

Source: https://docs.guance.com/owl/mcp-tools-reference/

Queries monitors. Used to list monitors.

```APIDOC
## owl.monitor.list

### Description
Queries monitors.

### Parameters
None specified in source.

### Permissions
Read-only

```