@guandata/guancli

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

安装

npm install -g --foreground-scripts @guandata/guancli

全局安装/升级时会通过 postinstall 自动执行一次 guancli install-skill 刷新 AI skill。--foreground-scripts 用于显示明确的成功、失败或跳过结果；失败时按提示手动运行 guancli install-skill。CI 等无需 skill 的环境可设 GUAN_SKIP_INSTALL_SKILL=1 跳过。

安装包会通过 npm optionalDependencies 自动选择当前系统的原生二进制。不要使用 --omit=optional 或 optional=false；企业 npm 镜像也需要同步对应的 @guandata/guancli-<平台>-<架构> 包。若平台包缺失，CLI 会显示对应包名和重新安装方法。

也可以直接使用：

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-file query.sql    # 从文件读取多行 SQL，避免 Shell 多层引号
guancli ds execute-sql -inputs <ds_id> --sql-file - < query.sql # 从 stdin 读取 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.61

• 指标取数会校验 --dim、--filter 和排序字段：未命中指标详情字段时返回明确错误，不再静默忽略条件。
• 排序支持保存卡片的高级计算列与泛化结果列名；唯一映射的公共维度名可用于维度、排序和筛选。

@guandata/guancli 1.0.60

• 新增内部 OAuth2 应用认证，按 GUANCLI_OAUTH2_* 整体注入环境与用户身份，CLI 不保存、不刷新该 Token。
• PAT 登录会保存登录 Domain；新增 ds get --validate-downstream 校验血缘下游资源是否仍存在。

@guandata/guancli 1.0.59

• 指标筛选支持 =、!=、<>、<、<=、>、>= 符号写法，统一归一化为枚举操作符；BT 也支持两个不含空格的边界用空格分隔。
• metric batch-query 新增 --fail-on-error，并在 valueFormat 中新增 both，一次取数同时返回原始值和展示值。
• ds execute-sql 新增 -o/--output，可直接把结果写入文件（默认 CSV）。
• app publish --overwrite-settings 仅在 BI >= 8.3.2 时生效，低版本默认保留线上设置。

@guandata/guancli 1.0.58

• 新增 metric batch-query：同轮已确定、互不依赖的多个基础指标查询可写成一份 JSON 一次提交，CLI 自动调度并发并按输入顺序逐项返回，失败逐项归因。
• 批量查询支持维度、日期子粒度、排序、分页和 valueFormat；格式化输出沿用指标格式配置，排序分页基于原始值。
• 指标结果消费补充动态列发现与精确选择规范，避免硬编码展示列名；登录方式顺序与提示同步更新。

@guandata/guancli 1.0.57

• 统一指标查询 JSON 契约，补充日期维度与筛选示例，并支持按状态搜索指标。
• 卡片预览会标注生效筛选及来源，支持运行态默认值和级联选择器。

@guandata/guancli 1.0.56

• 指标查询默认遵循指标或查询列的数值格式，覆盖货币、百分比、精度、千分位、数量级和前后缀。
• 新增 --value-format raw，可在标准表格、JSON、CSV 和 Excel 输出中保留原始数值。
• 登录和 Profile 加载会提前校验 BI 地址，减少 Windows 引号转义等配置问题造成的连接失败。

@guandata/guancli 1.0.55

• 新增本地 CSV/JSON 规范化、对齐、安全计算和分组 TopN 分析命令。
• 指标查询提供稳定 JSON envelope、结构化筛选文件和 dry-run 校验，复杂筛选更易自动化处理。
• 限制指标候选发现的搜索轮次，并强化精度、空值、重复键和输出文件保护。

@guandata/guancli 1.0.54

• SuperApp 发布支持复用可信、已验证的 dist，避免服务端因缺少项目本地构建工具而发布失败。
• 覆盖线上 SuperApp 配置前会明确确认，未确认时保留线上 setting.json。
• 指标问数命令、筛选与列选择更稳定，非法格式或拼错子命令会明确失败。
• 结构化错误会保留请求位置、状态码和后端业务原因，排障更直接。

@guandata/guancli 1.0.53

• 新增 OIDC 登录与安全凭据管理，企业统一身份认证和多环境切换更稳定。
• SuperApp 支持列出应用和整包下载，重名应用也能得到明确的后续处理提示。
• ds execute-sql 支持从文件或标准输入读取多行 SQL，并改进解析错误展示。
• 改进文件下载的完整性、超时和错误处理，并支持自动关联卡片继承筛选条件。

@guandata/guancli 1.0.52

• 新增资源全局搜索与资源 URL 获取能力，定位和访问 BI 资源更便捷。
• 指标搜索可返回指标详情，并优化登录、自动重登和查询稳定性。
• 修复表单与卡片筛选条件被忽略、误切或字段信息丢失等问题。
• 文件上传超时可通过 GUANCLI_UPLOAD_TIMEOUT 配置。

@guandata/guancli 1.0.51

• 指标查询结果会按查询优先级合理排序，指标检索与选择更准确。
• 修复大数据量子表的续增问题，超过 10000 行后仍可继续添加。

@guandata/guancli 1.0.50

• 指标查询结果会明确展示是否命中查询加速，命中时可看到相关加速指标信息，便于判断查询效果。
• 多环境使用时，Agent 可根据 Domain 或 BI 地址定位对应登录环境，减少环境选择错误。

@guandata/guancli 1.0.49

• 支持按 Domain 或 URL 查找 Profile，切换和定位目标环境更方便。
• 新增指标查询加速能力，提升指标查询效率。
• 指标查询结果超过 1000 行时默认转为文件输出，更适合处理大结果集。

@guandata/guancli 1.0.48

• 支持直接基于已有仪表板或智能洞察卡片生成洞察结果，可应用筛选条件并选择分析思路。
• 新增仪表板智能体问答，可选择专家、继续追问并查看历史会话。
• 修复指标查询排序，升序和降序配置可正确生效。

@guandata/guancli 1.0.47

• 卡片预览筛选支持使用卡片内重命名后的表头，也可继续使用数据集原始字段名。

@guandata/guancli 1.0.46

• 指标树支持按树名称和指标名称定位拆解子树，可直接查看指定指标下已配置的关联指标。
• 页面、ETL 等资源目录树支持按关键词和最大深度缩小范围，大型环境中更容易定位目标资源。
• 更新底层依赖，提升安全性和运行稳定性。

@guandata/guancli 1.0.45

• 卡片预览支持应用所在页面的默认筛选条件，覆盖常用选择器、日期粒度和动态参数；遇到多页面或无法确定的映射时会提前提示确认，避免静默返回错误结果。
• 动态参数会按当前卡片的实际配置解析，多个卡片使用不同参数时不再相互干扰。
• 认证状态检查会遵循当前 Profile，帮助 Agent 准确确认正在操作的目标环境。

@guandata/guancli 1.0.44

• 指标搜索支持多个关键词，并可同时匹配指标名称、业务口径和业务属性，结果会说明命中位置和优先级。
• 表单业务字段与系统展示列同名时可正确读取和写入，系统只读列会提前给出明确提示。
• 优化 Agent 的资源查询策略，优先使用轻量字段查询，减少大型环境中的等待和超时。

@guandata/guancli 1.0.43

• Token 登录引导和状态校验更准确，减少配置错误或失效凭证造成的反复排查。
• 优化多资源读取效率，页面、数据集和指标等批量分析场景响应更快。

@guandata/guancli 1.0.42

• 密码登录环境执行连接或认证状态检查时，token 过期或失效会自动重新登录并再次验证，减少 Agent 因会话过期而中断。
• 状态输出会明确区分自动恢复成功、凭证失效和暂时无法验证，便于快速判断下一步处理方式。

@guandata/guancli 1.0.41

• 增强复杂报表 Pro 子卡片的元数据读取与筛选支持，复杂报表分析结果更完整。
• 精简页面、数据集和 ETL 的可读输出，便于 Agent 直接定位关键信息。
• 全局安装或升级后自动刷新 AI Skill，并随包提供完整使用说明和参考资料。

@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

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