CLI 快速开始¶

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

前提条件¶

开始前请确认：

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

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

OWL CLI 支持通过环境变量、本地配置文件或独立 Profile 设置 Endpoint 和访问令牌。首次使用可选择前两种方式；需要保存多个账号或环境时，使用 Profile。

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

方式一：使用环境变量¶

bash / zshPowerShell

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

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

环境变量只在当前终端会话中生效。关闭终端后，如需继续使用，需要重新设置。

这种身份覆盖适用于尚未选择 Profile 的旧配置模式，或单独使用已弃用的 --conf。如果之前执行过 owl switch，或设置了 --profile / OWL_PROFILE，OWL 会使用所选 Profile 的 Endpoint/Key。可用 owl profile current 查看当前来源。

访问令牌也可以通过 OWL_API_KEY 设置；当 OWL_API_KEY 与 OWL_TOKEN 同时存在时，OWL CLI 以 OWL_API_KEY 为准。

方式二：写入本地配置文件¶

owl init
owl login

执行说明：

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

未选择 Profile 时，本地配置会写入 ${OWL_DIR}/config.yaml，默认是 ~/.owl/config.yaml。选中 Profile 后，init 和 login 写回所选配置。

仅在旧配置模式或单独使用 --conf 时，身份环境变量优先于配置文件。

方式三：保存独立 Profile¶

owl profile add customer-a
owl profile add customer-b --from ./customer-b.yaml
owl profile list
owl switch customer-a
owl profile current

profile add 交互输入 Endpoint 和 Key，也可用 --from 复制已有 YAML。新增只保存配置，不改变当前选择；switch 保存后续命令的默认选择。每个命名 Profile 使用独立配置、缓存和查询文件目录。

单次命令可以临时选择另一份配置，不改变默认：

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

选择优先级为 --profile > OWL_PROFILE > 持久化选择。完整用法见使用多个 Profile。

第二步：同步工具目录¶

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

owl sync

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

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

owl sync -c data

第三步：查看工具¶

查看所有工具分类：

owl category list

查看某个分类下的工具：

owl list -c data

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

owl show owl.data.query

第四步：执行前校验¶

在不发起实际查询的情况下，先校验工具调用：

owl validate owl.data.show_dql_namespace -f json

结果中的 valid 应为 true，request_executed 应为 false。如果当前 CLI 不支持 validate，请升级到 1.2.0 或更高版本。

第五步：执行工具¶

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

owl exec owl.data.show_dql_namespace

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

owl exec owl.data.show_dql_namespace -f json

完整示例¶

bash / zshPowerShell

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

$env:OWL_REGISTRY_ENDPOINT = "your-owl-endpoint"
$env: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 sync 可以正常完成，不返回认证或网络错误
owl category list 可以看到工具分类
owl list -c data 可以看到 data 分类下的工具
owl validate owl.data.show_dql_namespace -f json 返回 valid: true 和 request_executed: false
owl exec owl.data.show_dql_namespace 可以返回当前工作空间支持的 DQL 命名空间

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