@guandata/guancli

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

安装

npm install -g @guandata/guancli

也可以直接使用：

npx @guandata/guancli auth login

常用命令

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.40

• 卡片预览会保留多级表头层级并生成稳定、唯一的列名，复杂交叉表导出、选列和排序结果更准确。
• 卡片自带筛选字段元数据时不再强制读取数据集字段，权限受限场景也能正确应用筛选并完成预览。
• 表单更新说明明确要求携带全部业务主键字段，帮助 Agent 在修改数据前准备完整且可执行的更新载荷。

@guandata/guancli 1.0.39

• etl get 可读输出新增有效调度状态，综合 config.enableSchedule、triggerType、CRON 和上游级联开关判断真实自动触发状态，避免 schedule --disable 后底层触发字段残留造成误判。
• 工作流资源查询能力增强，支持查看工作流目录、节点和执行相关信息，便于排查数据流编排。
• 指标查询文档和只读能力收敛，指标创建/编辑等写操作迁移到独立 guanmetric 组件。

@guandata/guancli 1.0.38

• 新增 Personal Access Token 登录方式，支持在自动化、CI 或无浏览器环境中使用 PAT 完成认证。
• auth 相关命令增强 PAT profile 的状态展示和修改保护，避免把 PAT 配置误当普通登录配置处理。
• API 调用会根据当前认证上下文选择合适的身份信息，提升 PAT 场景下调用 ChatBI、指标和资源接口的稳定性。

@guandata/guancli 1.0.37

• 新增 Personal Access Token 登录方式，支持在自动化、CI 或无浏览器环境中使用 PAT 完成认证。
• auth 相关命令增强 PAT profile 的状态展示和修改保护，避免把 PAT 配置误当普通登录配置处理。
• API 调用会根据当前认证上下文选择合适的身份信息，提升 PAT 场景下调用 ChatBI、指标和资源接口的稳定性。

@guandata/guancli 1.0.36

• metric 增加指标主题和指标目录创建能力，便于直接准备指标管理结构。
• 补充 SuperApp 创建指导，帮助 Agent 按应用和页面场景组织 BI 配置。
• 页面资源搜索和结果展示增强，按名称或 ID 查找页面时结果更稳定、更易读。
• install-skill 适配 WorkBuddy 配置目录，提升本机编码助手安装兼容性。

@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

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