CLI 命令¶

本文档介绍 OWL CLI 的常用命令，包括配置与认证、工具目录同步、工具查看、执行前校验、工具执行、缓存管理、数据文件管理，以及面向 Agent 的能力协商与 Schema 输出。

配置与认证¶

OWL CLI 使用以下常用配置：

常用命令：

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

全局 --conf <path> 参数可为单次命令选择另一份已经存在的配置文件，适合在不同授权或 Endpoint 之间切换：

owl --conf ~/.owl/prod.yaml config show
owl --conf ~/.owl/prod.yaml sync
owl --conf ~/.owl/testing.yaml exec owl.metric.list --mode source

init、login、config set、workspace use 等写操作会写回 --conf 指定的文件。不传该参数时，OWL 继续使用 ${OWL_DIR}/config.yaml；默认路径为 $HOME/.owl/config.yaml。

如果本地开发环境的 Registry 使用自签名证书，可以显式关闭证书校验：

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

该设置默认是 false。开启后 OWL 无法验证 Registry 的身份，可能遭受中间人攻击，不应在生产环境使用。

workspace 命令也可写作别名 workspaces。

设置访问令牌时，api-key 与 token 这两个键名是等价的，写入任意一个都会更新到同一个访问令牌；工作空间级令牌也遵循同样的等价规则。

owl workspace same-org list¶

列出与当前账号同组织（same-org）的工作空间。支持的 flags：

分页规则：

• 默认只返回一页。若仍有更多结果，文本输出会提示 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
  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

配置优先级从高到低如下：

1. 环境变量
2. --conf 指定的配置文件（设置该参数时）
3. ${OWL_DIR}/config.yaml（未设置 --conf 时）

registry.request_timeout 控制单次 Registry HTTP 请求的总超时，单位为毫秒。默认值 150000 高于数据查询工具的 130 秒服务端期限，为响应编码和网络传输预留时间；仅在明确了解上游查询耗时的情况下调整。

缓存与同步¶

owl sync 会将 观测云 中的分类和工具元数据同步到本地缓存目录。

以下场景需要重新执行 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