CLI 命令¶

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

配置与认证¶

Owl CLI 使用以下两个核心配置：

配置项	说明
`OWL_REGISTRY_ENDPOINT`	工作空间所属站点对应的 Owl CLI Endpoint
`OWL_TOKEN`	服务访问令牌，用于标识调用方身份，对应 DF-API-KEY

常用命令：

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

命令	说明
`owl init`	写入 Owl CLI Endpoint
`owl login`	写入访问令牌
`owl config show`	查看当前配置
`owl config set <配置项> <值>`	修改指定配置项

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

分类与工具目录¶

查看分类和工具前，建议先执行一次同步：

owl sync

分类与工具查看命令：

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

命令	说明
`owl category list`	查看所有分类
`owl category show <分类ID>`	查看分类详情和分类下工具
`owl list`	查看全部工具
`owl list -c <分类ID>`	查看某个分类下的工具
`owl show <工具名>`	查看工具详情和参数定义

工具执行¶

使用 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

配置文件与优先级¶

默认配置文件路径：

操作系统	配置文件路径
Windows	`%USERPROFILE%\.owl\config.yaml`
Linux / macOS	`$HOME/.owl/config.yaml`

配置文件示例：

registry:
  endpoint: your-owl-endpoint
  sync_interval: 3600

auth:
  token: ""

cache:
  directory: ~/.owl/cache
  ttl: 86400

data:
  directory: ~/.owl/data
  max_age_days: 30

sync:
  parallel: true
  concurrency: 5
  incremental: true

execution:
  default_timeout: 30000
  max_output_size: 10485760

logging:
  level: info
  file: ~/.owl/logs/owl.log

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

环境变量
config.yaml

缓存与同步¶

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

以下场景需要重新执行 owl sync：

首次安装完成后
平台发布了新的工具
平台更新了已有工具的参数或说明
需要刷新本地缓存内容

常用同步与缓存命令：

命令	说明
`owl sync`	同步全部分类和工具
`owl sync -c <分类ID>`	只同步指定分类
`owl cache status`	查看缓存状态
`owl cache clear`	清理全部缓存
`owl cache clear -c <分类ID>`	清理指定分类缓存

数据结果文件¶

当工具定义的输出类型为 data 时，Owl CLI 会自动将结果文件保存到本地 data/ 目录，并记录文件索引与结构信息。

常用数据文件命令：

命令	说明
`owl data list`	查看数据文件列表
`owl data show <file-id>`	查看指定数据文件详情
`owl data rm <file-id>`	删除指定数据文件
`owl data clean --days <天数>`	清理指定天数以前的历史文件
`owl data stats`	查看数据文件统计信息

面向 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