跳到主要内容
版本：8.2.0

GuanCLI 使用指南

说明

目前产品处于测试阶段，免费提供使用，后续会逐步收费，如仍需体验请联系观远数据商务人员或客户成功经理（通常是贵公司当前的服务交流负责人）。

GuanCLI 是什么

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

前提条件

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

检查当前环境

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

node -v
npm -v

如果输出类似 v22.x.x（或更高）和 10.x.x，说明环境已就绪，可直接进入安装 GuanCLI。

|300

安装 Node.js

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

方式一：手动下载安装

  1. 打开浏览器，访问 Node.js 中文下载页面。

  2. 在页面中选择你的操作系统（如 Windows、macOS），并选择「安装程序」方式，下载推荐的长支持版本（LTS，例如 v24.x）。

  3. 运行下载好的安装包，按安装向导一直点击「下一步」即可完成安装

  4. 重新打开终端（安装后旧终端窗口不会自动识别新环境），再次执行 node -v 和 npm -v 验证

说明

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

方式二：通过 Agent 自动安装

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

帮我安装Node.js V22+

安装 GuanCLI

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

  1. 安装 GuanCLI

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

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

  2. 安装完成后验证

    guancli version

    终端显示版本号即表示安装成功。

    |300

    说明

    如果安装成功但执行 guancli version 提示找不到命令，通常是 npm 全局命令目录未加入系统 PATH。可执行 npm prefix -g 查看全局目录，将其下的 bin 目录加入 PATH 后重新打开终端。

  3. (可选) 查看安装位置

    npm list -g @guandata/guancli

    |350

  4. 安装 SKILL

    guancli install-skill

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

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

方式二：通过 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

安装完成页面：

登录 GuanCLI

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

在终端输入下方命令：

guancli auth login

按提示依次输入：

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

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

登录方式

方式一：账号密码登录

获取账密步骤：

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

登录成功页面：

方式二：Token 登录

说明

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

获取 Token 步骤：

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

登录成功页面：

切换登录环境

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

查看所有环境：

guancli auth list

切换默认环境：

guancli auth use <环境名称>

查看登录状态

guancli auth status
guancli auth whoami

常见问题排查

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

先确认安装成功：

npm list -g @guandata/guancli

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

npm prefix -g

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

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

  1. 查看状态

    guancli auth status

  2. 重新登录

    guancli auth login

问题三：Token 过期

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

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

guancli auth login

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

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

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