CLI 快速开始¶

本文档面向首次使用 Owl CLI 的用户，介绍如何完成 Owl CLI 配置、同步工具目录，并执行一次工具调用。

前提条件¶

开始前请确认：

1. 已完成 手动安装 Owl 或 自动安装 Owl
2. 已获取工作空间所属站点对应的 Owl CLI Endpoint，可参考 Endpoint 列表
3. 已获取访问令牌 OWL_TOKEN ，对应 DF-API-KEY
4. 当前终端可以访问 Owl CLI Endpoint

第一步：配置 Endpoint 和访问令牌¶

Owl CLI 支持通过环境变量或本地配置文件设置 Endpoint 和访问令牌。

OWL_REGISTRY_ENDPOINT 只填写 Endpoint 根地址，不要手动拼接 /api/v1 或其他路径。

方式一：使用环境变量¶

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 init
owl login

执行说明：

• owl init 用于写入 Owl CLI Endpoint
• owl login 用于写入访问令牌

本地配置会写入 Owl CLI 配置目录，后续打开新的终端也可以继续使用。

环境变量优先级高于配置文件。当前终端中如果已经设置环境变量，Owl CLI 会优先使用环境变量中的值。

第二步：同步工具目录¶

首次使用 Owl CLI 前，需要先同步工具目录：

owl sync

owl sync 会把 观测云 当前可用的分类和工具元数据同步到本地缓存。同步完成后，才可以查看和执行工具。

如果只需要同步某个分类，可以使用 -c 指定分类：

owl sync -c metric

第三步：查看工具¶

查看所有工具分类：

owl category list

查看某个分类下的工具：

owl list -c metric

查看某个工具的参数说明：

owl show owl.metric.list

第四步：执行工具¶

执行以下命令，查询当前工作空间可访问的指标来源：

owl exec owl.metric.list --mode source

如需机器可读输出，可以指定 JSON 格式：

owl exec owl.metric.list --mode source --format json

完整示例¶

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

owl sync
owl category list
owl list -c metric
owl show owl.metric.list
owl exec owl.metric.list --mode source --format json

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

owl sync
owl category list
owl list -c metric
owl show owl.metric.list
owl exec owl.metric.list --mode source --format json

成功标准¶

完成快速开始后，应能达到以下结果：

• owl sync 可以正常完成，不返回认证或网络错误
• owl category list 可以看到工具分类
• owl list -c metric 可以看到 metric 分类下的工具
• owl exec owl.metric.list --mode source 可以返回当前可访问的指标来源

如果遇到认证失败、工具不存在、结果为空等问题，请查看 故障排查。