版本：8.2.0

GuanCLI 使用指南

更新时间：2026-06-25 10:58:08

说明

目前产品处于公测阶段，可以免费使用所有功能，公测后需要获得商业授权才能继续使用，如仍需体验请联系观远数据商务人员或客户成功经理（通常是贵公司当前的服务交流负责人）。

GuanCLI 是什么

GuanCLI 是观远 BI 官方命令行工具，通过终端即可查询 BI 资源、预览数据、排查任务、操作表单和调用 ChatBI。配合 Skill，用户可通过自然语言让 Agent 获取数据、排查问题，大幅提升分析与运维效率。

你可以把 GuanCLI 理解为“给 AI 和技术人员使用的 BI 工具箱”。它不替代 BI 产品界面，而是让 AI Agent、数据分析师、实施顾问和 IT 人员能在受控环境中更快地读取和检查 BI 资源。

典型使用场景

场景	可以怎么用
查找 BI 资源	按名称搜索数据集、页面、卡片、ETL 和任务，快速定位资源 ID 与目录。
分析数据口径	查看数据集字段、卡片来源、页面结构和 ETL 上游逻辑。
排查运行问题	查看失败任务、ETL 运行状态和错误信息，辅助定位原因。
调用 ChatBI	让 AI 基于已有 ChatBI 主题问数或发起洞察分析。
辅助生成资源	与 GuanVis、GuanETL 配合，生成看板初稿或修改 ETL 草稿。

如果你的目标是让业务人员在飞书 Aily、DecideX 或企业自研 AI 助手中直接问数，请优先阅读 GuanMCP 使用指南。GuanCLI 更适合需要 AI 主动查询、排查、生成或修改 BI 资产的场景。

前提条件

安装 GuanCLI 前请确认电脑已安装 Node.js V22 或更高版本，并自带了 npm。

检查当前环境

在终端中执行以下命令查看版本：

node -v
npm -v

如果 Node.js 输出为 v22.x.x（或更高），且 npm -v 能正常输出版本号，说明环境已就绪，可直接进入安装 GuanCLI。

安装 Node.js

如果提示找不到命令，或版本低于 V22，需要重新安装。

方式一：手动下载安装

打开浏览器，访问 Node.js 中文下载页面。
在页面中选择你的操作系统（如 Windows、macOS），并选择「安装程序」方式，下载推荐的长支持版本（LTS，例如 v24.x）。
运行下载好的安装包，按安装向导一直点击「下一步」即可完成安装
重新打开终端（安装后旧终端窗口不会自动识别新环境），再次执行 node -v 和 npm -v 验证

说明

安装 Node.js 时通常会自动安装 npm，并默认将相关命令加入系统 PATH。如果验证时仍提示找不到命令，请检查环境变量配置。

方式二：通过 Agent 自动安装

复制下方提示词给 Agent（Claude Code、Codex、Cursor、Trae 等），Agent 会自动完成安装和配置。

帮我安装Node.js V22+

安装 GuanCLI

方式一：通过 npm 命令全局安装

安装 GuanCLI

# 首次安装  
npm install -g @guandata/guancli  

# 已安装过的更新版本  
npm update -g @guandata/guancli

安装完成后验证
```
guancli version
```
终端显示版本号即表示安装成功。

说明
如果安装成功但执行 guancli version 提示找不到命令，通常是 npm 全局命令目录未加入系统 PATH。macOS/Linux 可执行 npm prefix -g 查看全局目录，并将其下的 bin 目录加入 PATH；Windows 请将 %AppData%\npm 加入 PATH。完成后重新打开终端。
(可选) 查看安装位置
```
npm list -g @guandata/guancli
```
安装 SKILL，让 Agent 知道什么时候使用 GuanCLI。

执行以下命令安装 Skill：
```
guancli install-skill
```
关于 Skill 的详细说明，可参考本文档中的安装 Skill 章节。

方式二：通过 Agent 自动安装

复制下方提示词给 Agent（Claude Code、Codex、Cursor、Trae 等），Agent 会自动完成安装和配置，后续即可直接在 Agent 中通过自然语言进行提问。

帮我安装GuanCLI：https://www.guandata.com/guandata-cli-installation-guide.md

如果安装过程中卡住了，可以让 Agent 使用阿里源下载：

使用 https://registry.npmmirror.com 作为 npm 源帮我安装 GuanCLI

安装完成页面：

安装 Skill

GuanCLI 除了提供命令行工具外，还提供了一套 Skill 能力。Skill 可以理解为给 AI 助手准备的一套BI 工具使用说明，安装后，AI 助手（如 Claude Code、Cursor、Codex 等）就知道什么时候该调用 GuanCLI、该调用哪个命令、参数怎么填。

举个例子：

没装 Skill 时，你对 AI 说 " 帮我查一下销售数据集 "，AI 可能不知道该怎么操作。
装了 Skill 后，AI 会自动识别你的意图，并调用 guancli dataset list 或 guancli dataset search 等命令完成查询。

因此，如果你想让 AI 用自然语言帮你操作 BI，必须安装 Skill。

安装方式很简单：

guancli install-skill

安装完成后，即可在 AI 工具中用自然语言提问，例如：

帮我列一下当前 BI 环境的数据集目录。

更新 GuanCLI

更新一次执行以下指令

# 进行guancli更新  
npm update -g @guandata/guancli  

# 再次安装skill  
guancli install-skill

安装完成后验证
```
guancli version
```

登录 GuanCLI

使用 guancli 前，需要先配置 BI 系统地址和认证信息。CLI 与 Skill 共用同一份认证配置。只要 guancli auth login 登录成功，Skill 后续调用 CLI 时会自动复用当前认证信息。

在终端输入下方命令：

guancli auth login

按提示依次输入：

环境名称：默认 default，也可以填写 prod、test 等。给不同 BI 环境起不同名称，是为了在本地保存多份登录配置，方便后续快速切换。例如测试环境叫 test，生产环境叫 prod，后续通过 guancli auth use <环境名称> 就能秒切环境，不用重新输 URL 和账号密码
BI 系统 URL：需要登录的 BI 地址，例如 https://demo.guandata.com
登录方式：选择登录方式，可选「用户名密码登录」或「直接输入 Token」，详细可参考登录方式
Domain（选择用户名密码登录时需要配置）：多租户/私有化部署时使用的域标识，一般用户直接回车留空，CLI 会自动探测；如果你的管理员明确告知了 Domain，请按其填写
Login ID（选择用户名密码登录时需要配置）：登录账号
Password（选择用户名密码登录时需要配置）：登录密码

登录成功后，Token 会自动保存到本机，后续命令无需重复登录。

登录方式

方式一：账号密码登录

获取账密步骤：

账号密码可登录 BI 环境获取，点击右上角头像可查看登录账号，若不清楚登录密码，请联系管理员获取。

登录成功页面：

方式二：Token 登录

说明

由于 token 有效期较短，建议使用账号密码登录。

获取 Token 步骤：

在浏览器中打开并登录 BI 系统
在 BI 页面任意空白处右键，点击「检查」（Chrome/Edge）或「检查元素」（Firefox），打开开发者工具
切换到「应用」（Application）标签页
在左侧「存储 > Cookie」中点击当前 BI 域名
找到名为 uIdToken 的 Cookie，复制其 Value 列的值，即为登录 Token

登录成功页面：

切换登录环境

guancli 支持在一台电脑上保存多个 BI 环境配置，例如测试环境、生产环境、客户 A 环境、客户 B 环境。

查看所有环境：

guancli auth list

切换默认环境：

guancli auth use <环境名称>

查看登录状态

guancli auth status
guancli auth whoami

使用 GuanCLI 的常用工作流

安装 Skill 后，更推荐直接在 Claude Code、Cursor、Codex 等 AI 工具中用自然语言提问。AI 会根据问题自动调用 GuanCLI，并把结果整理给你。

开始正式使用前，可以先让 AI 检查当前登录环境：

请先检查当前 GuanCLI 登录环境，并确认能正常访问 BI。

AI 可能会执行：

guancli auth status
guancli auth whoami
guancli bi info

如果你的目标只是查询 BI 资源、预览数据、排查任务、操作表单或调用 ChatBI，使用 GuanCLI 即可；如果要生成仪表板或开发 ETL，再继续使用 GuanVis 或 GuanETL。

分析 BI 资源

可以让 AI 帮你：

搜索某个 ETL、数据集、页面或卡片。
查看 ETL 节点、SQL、输入输出和血缘。
查看数据集字段结构、字段类型、维度、度量、计算字段和血缘。
查看页面中有哪些卡片、筛选器和交互配置。
查看卡片的数据集来源、图表配置和预览数据。

示例提问：

帮我看一下“销售经营看板”这个页面用了哪些数据集。

AI 可能会执行：

guancli page search 销售经营看板
guancli page get <page_id>
guancli card get <cd_id>
guancli ds get <ds_id>

按名称查找数据集并预览数据

可以让 AI 直接处理：

帮我看一下销售明细数据集里，2026 年 1 月上海的数据，按销售额倒序取前 20 行。

AI 可能会执行：

guancli ds search 销售
guancli ds get <ds_id>
guancli ds preview <ds_id> \
  --filter "日期 toMonth EQ 2026-01" \
  --filter "城市 EQ 上海" \
  --sort-desc 销售额 \
  --limit 20

从页面找到卡片，再查看卡片数据

示例提问：

帮我找到“经营看板”里的核心指标卡片，并预览卡片数据。

AI 可能会执行：

guancli page search 经营看板
guancli page get <page_id>
guancli card get <cd_id>
guancli card preview <cd_id> --limit 20

排查 ETL 和数据口径

示例提问：

这个销售汇总数据集是哪个 ETL 生成的？帮我看下上游 SQL 逻辑。

AI 可能会执行：

guancli ds search 销售汇总
guancli ds get <ds_id> --assoc
guancli etl get <etl_id>

如果要排查失败任务，可以这样问：

帮我看一下最近失败的 ETL 任务，说明失败原因和下一步排查建议。

AI 可能会执行：

guancli task history --status Failed --task-types ETL_COMBINED
guancli task get <task_id>
guancli task detail <task_id>

查询和维护表单填报数据

示例提问：

帮我查一下客户回访表里状态为“待处理”的记录，并把第一条改成“已处理”。

AI 可能会执行：

guancli form list 客户回访
guancli form schema <fmId>
guancli form query <fmId> --filter "状态 EQ 待处理" -f json
guancli form update <fmId> <rowId> --set "状态=已处理"

注意

涉及写入、更新、删除表单数据时，先让 AI 展示即将操作的 fmId、rowId 和字段变更内容，确认后再执行。

使用 ChatBI 问数和洞察

示例提问：

用 ChatBI 的经营主题问一下最近 30 天营业收入是多少。

AI 可能会执行：

guancli chatbi list-theme
guancli chatbi query --theme-name "经营主题" --message "最近30天营业收入是多少？"

洞察分析示例：

用 ChatBI 的经营主题分析最近 30 天营业收入变化原因。

AI 可能会执行：

guancli chatbi insight \
  --theme-name "经营主题" \
  --message "分析最近30天营业收入变化原因"

查询指标和指标归因

示例提问：

帮我查一下“销售额”这个指标的业务口径，并按渠道看最近的数据。

AI 可能会执行：

guancli metric search 销售额
guancli metric get <metric_id>
guancli metric query <metric_id> --dim 渠道 --limit 20

指标归因示例：

帮我看一下销售相关指标树，并按渠道分析指标变化原因。

AI 可能会执行：

guancli metric_attribution search 销售
guancli metric_attribution get <metric_tree_id>
guancli metric_attribution query <metric_tree_id> --target dim --dim 渠道

权限和安全说明

GuanCLI 调用观远 BI 时，会使用当前登录用户或当前 Token 的权限。能看到哪些资源、能执行哪些操作，取决于该用户在 BI 中的权限配置。

使用时请注意：

不要在公开聊天、工单或文档中粘贴账号密码、Token、客户隐私数据或敏感业务数据。
使用 Agent 自动操作前，先确认当前 guancli auth status 指向的环境和账号。
只读查询和数据预览通常风险较低；表单更新、资源保存、页面发布、ETL 保存/运行/删除属于高风险操作。
高风险操作前，请让 AI 列出目标资源 ID、资源名称、变更内容和预计影响范围。
建议为试点和演示准备独立测试账号，避免直接使用高权限生产账号。

常见问题排查

问题一：安装后提示找不到 guancli 命令

先确认安装成功：

npm list -g @guandata/guancli

再检查 npm 全局命令目录是否在 PATH 中：

npm prefix -g

Windows 全局命令通常位于 %AppData%\npm，macOS/Linux 位于 $(npm prefix -g)/bin。

问题二：提示未登录或认证失败

查看状态
```
guancli auth status
```
重新登录
```
guancli auth login
```

问题三：Token 过期

如果使用用户名密码登录，并保存了密码，工具会尝试自动重新登录。

如果使用 Token 登录，或没有保存密码，需要重新执行：

guancli auth login

问题四：GuanCLI 是否有 BI 版本依赖

基本无硬性依赖，核心功能（如卡片读取、数据集读取、表单操作等）在 BI 7.x 即可使用。

少数 API 可能依赖较新版本，例如「超级应用初始化」目前依赖 BI 8.2 版本，在低版本环境调用时会存在调用失败的可能性。如遇到此类情况，建议升级 BI 至对应版本后重试。

GuanCLI 是什么​

典型使用场景​

前提条件​

检查当前环境​

安装 Node.js​

方式一：手动下载安装

方式二：通过 Agent 自动安装

安装 GuanCLI​

方式一：通过 npm 命令全局安装​

方式二：通过 Agent 自动安装​

安装 Skill​

更新 GuanCLI​

登录 GuanCLI​

登录方式​

方式一：账号密码登录

方式二：Token 登录

切换登录环境​

查看登录状态​

使用 GuanCLI 的常用工作流​

分析 BI 资源​

按名称查找数据集并预览数据​

从页面找到卡片，再查看卡片数据​

排查 ETL 和数据口径​

查询和维护表单填报数据​

使用 ChatBI 问数和洞察​

查询指标和指标归因​

权限和安全说明​

常见问题排查​

问题一：安装后提示找不到 guancli 命令​

问题二：提示未登录或认证失败​

问题三：Token 过期​

问题四：GuanCLI 是否有 BI 版本依赖​

GuanCLI 是什么

典型使用场景

前提条件

检查当前环境

安装 Node.js

安装 GuanCLI

方式一：通过 npm 命令全局安装

方式二：通过 Agent 自动安装

安装 Skill

更新 GuanCLI

登录 GuanCLI

登录方式

切换登录环境

查看登录状态

使用 GuanCLI 的常用工作流

分析 BI 资源

按名称查找数据集并预览数据

从页面找到卡片，再查看卡片数据

排查 ETL 和数据口径

查询和维护表单填报数据

使用 ChatBI 问数和洞察

查询指标和指标归因

权限和安全说明

常见问题排查

问题一：安装后提示找不到 guancli 命令

问题二：提示未登录或认证失败

问题三：Token 过期

问题四：GuanCLI 是否有 BI 版本依赖