# @guandata/guancli

观远 BI 命令行工具，用于查看、搜索、预览和诊断 BI 资源，并提供 ChatBI 问数/洞察能力。

## 安装

```bash
npm install -g @guandata/guancli
```

也可以直接使用：

```bash
npx @guandata/guancli auth login
```

## 常用命令

```bash
guancli auth login
guancli auth whoami
guancli etl tree
guancli etl get <resource_id>
guancli ds search <keyword>
guancli ds preview <ds_id>
guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20'  # 需目标 BI 满足 8.2.0-hf12+，并在 BI 管理后台 - 域设置打开高级 SQL 查询开关
guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20' -f json
guancli ds execute-sql -inputs <ds_id> -sql 'SELECT * FROM `数据集名称` LIMIT 20' --raw
# SQL 中请使用数据集名称作为临时表名；名称包含中文、空格或特殊字符时，请使用反引号包裹。
# 旧版 public-api fallback 不支持 disable-cache；--limit 在非 raw 输出渲染前本地截断，--raw 保持后端原始响应
guancli metric project
guancli metric project 经营 -f json
guancli metric by-dataset <ds_id> -f json  # 查询数据集直接原子指标及下游复合/衍生指标
guancli page get <page_id>
guancli card preview <card_id>
guancli card preview <card_id> --dynamic-param "结束时间={{{today}}}"
guancli chatbi query --theme-name "经营主题" --message "最近30天营业收入是多少？"
```

## 版本更新

### @guandata/guancli 1.0.35

- `metric by-dataset` 增强数据集下游指标查询，并补充指标创建/编辑参考说明。
- `login status` 使用服务端 profile 校验登录状态，减少本地缓存状态误判。
- 数据集字段输出增加 raw name、alias/displayName 疑似误用提示，便于 ETL 和指标配置前排查字段引用。

### @guandata/guancli 1.0.34

- `metric by-dataset` 优先使用后端批量接口按数据集 ID 反查直接原子指标和下游复合/衍生指标，旧版 BI 会自动回退到本地扫描逻辑。

### @guandata/guancli 1.0.33

- `ds search` 支持按数据集 ID 精确解析，修复按 ID 搜索时无法稳定命中资源的问题。
- 资源详情查询补充相关解析兼容处理，提升数据集排查稳定性。

### @guandata/guancli 1.0.32

- `metric` 增加指标创建、编辑和删除能力，并补充原子指标、派生指标、复合指标等配置参考。
- `metric` 支持公共维度查询与配置辅助，便于按主题准备指标口径。
- 数据集详情输出补充字段信息，页面详情会标记 backlog 卡片，资源诊断信息更完整。
- 补充指标命令、数据集字段解析和页面渲染相关测试覆盖。

### @guandata/guancli 1.0.31

- `card preview` 会按卡片值格式设置输出展示值，支持小数位、百分比、千分位、前后缀等常见格式。
- `card preview` 保留 raw 原始值，避免展示格式影响排序、Excel/JSON 输出或后续处理。
- `ds execute-sql` 能力要求提示更清晰；认证请求默认不再额外发送 `X-AUTH-TOKEN`，提升部分环境兼容性。
- `install-skill` 增加 WorkBuddy skill 安装路径支持。

### 1.0.30

- `card preview --dynamic-field` 支持当前卡片自身的多选动态维度覆盖，可用逗号分隔字段或重复传参合并。
- `card preview` 动态维度参数校验与输出诊断增强，便于确认实际预览使用的动态维度选择。
- 简版资源详情减少非必要血缘明细加载，提升资源信息查询速度和稳定性。

### 1.0.29

- `card preview` 支持复杂报表 Pro 卡片预览，适配复杂报表筛选条件和数据输出。
- `card preview --dynamic-field` 支持按动态维度名和字段名指定预览选择，同时保留 dzId/key 等精确写法。
- `card preview -o` 输出大结果文件时补充字段 schema 提示，便于后续读取和处理导出的卡片数据。
- `ds execute-sql` 文档和提示补充数据集名称作为临时表名的说明。

### 1.0.28

- 卡片预览支持动态参数默认值，可在预览时自动带入可验证的动态维度选择。
- 增强动态维度配置校验，对缺少来源卡片、字段映射不完整或无法确认的配置提前报错。
- 卡片信息输出补充动态参数相关摘要，便于排查筛选器和图表联动配置。

### 1.0.27

- 新增 `metric project` 命令，支持查看当前用户可访问的指标主题，并可按主题名称关键词过滤。
- 指标主题列表会展示主题 ID、名称、备注和累计指标数量，便于后续限定指标搜索范围。
- 补充指标主题查询相关测试和命令参考文档，提升指标 CLI 使用说明的完整性。

### 1.0.26

- 新增 `ds execute-sql` 命令，支持对一个或多个数据集执行 SQL 查询，并提供 JSON/CSV/表格等输出。
- `ds execute-sql` 支持旧版 public-api fallback，兼容未开放新接口的 BI 环境。
- 改进卡片预览写入 `/dev/stdout` 时的输出行为，避免混入非数据日志。
- 增强卡片表格输出的稳定性，排序时可处理不完整行数据。

### 1.0.25

- 指标查询能力增强，补充指标泛化查询、同环比、最近周期、占比、Top N 排名等参数说明和参考文档。
- 新增 `server-version` / `bi-version` 命令，可查看当前 BI 版本，并在指标泛化查询前进行版本兼容性检查。
- 登录流程补充隐私协议提示，便于首次授权时确认使用前提。
- 优化数据集字段信息解析能力，便于在筛选和指标相关场景中复用字段元数据。

### 1.0.24

- 新增卡片预览数据分页能力，提升大数据量预览时的可用性与稳定性。
- 修复 `ds get` 对计算字段的统计和展示，数据集信息输出更完整。
- 当 API 返回“资源不存在”时，错误信息会追加当前 `profile` 提示，便于排查环境或账号配置问题。
- 改进 Windows npm 启动脚本，减少中文输出乱码。
- 更新文档中的命令命名，适配去除 `-skill` 后缀后的包与 CLI 使用方式。

### 1.0.23

- 新增 workflow 相关只读分析入口，支持查看和诊断工作流资源。
- 优化登录状态校验，会向服务端确认 Token 可用性，降低本地状态与真实登录状态不一致的问题。
- 改进调用链路的来源识别与请求元数据，提升与各 AI skill 协同调用时的稳定性。

### 1.0.22

- 增强文件下载类 API 能力，支持页面截图等二进制结果稳定写入本地文件。
- 补充能力边界与 ETL preview 0 行排查说明，便于区分只读分析、看板构建、ETL 编辑和数据集管理等使用场景。
- 优化命令执行稳定性，避免后台辅助任务影响主命令响应。

### 1.0.21

- 修复 CLI 运行时错误输出会附带 usage 帮助的问题，使实际错误信息更清晰。
- 补充相关命令测试，提升错误输出行为的稳定性。

### 1.0.20

- 指标 API 与 `guancli metric` 增加泛化查询能力，支持更灵活的指标查询场景。
- 卡片预览能力增强，提高预览数据量上限，并新增 Excel 导出支持。

### 1.0.19

- 支持显式指定配置目录，便于在脚本、多环境或隔离运行场景中加载指定配置。
- 补充配置目录相关测试，提升配置加载行为的稳定性。