GuanCLI 使用指南
GuanCLI 是什么
GuanCLI 是观远 BI 官方命令行工具，通过终端即可查询 BI 资源、预览数据、排查任务、操作表单和调用 ChatBI。配合 Skill，用户可通过自然语言让 Agent 自动调用 API 获取数据、排查问题，大幅提升分析与运维效率。
前提条件
安装 GuanCLI 前请确认电脑已安装 Node.js 和 npm：
node -v
npm -v
如果提示找不到命令，请先前往 nodejs.org 下载并安装 LTS 版本，安装完成后重新打开终端再执行检查。
安装 GuanCLI
方式一：通过 npm 命令全局安装
-
安装 GuanCLI
# 首次安装
npm install -g @guandata/guancli
# 已安装过的更新版本
npm update -g @guandata/guancli -
安装完成后验证
guancli version终端显示版本号即表示安装成功。
说明如果安装成功但执行
guancli version提示找不到命令，通常是 npm 全局命令目录未加入系统PATH。可执行npm prefix -g查看全局目录，将其下的bin目录加入PATH后重新打开终端。 -
(可选) 查看安装位置
npm list -g @guandata/guancli
-
安装 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
登录 GuanCLI
使用 guancli 前，需要先配置 BI 系统地址和认证信息。CLI 与 Skill 共用同一份认证配置。只要 guancli auth login 登录成功，Skill 后续调用 CLI 时会自动复用当前认证信息。
在终端输入下方命令：
guancli auth login
按提示依次输入：
- 环境名称：默认
default - BI 系统 URL：需要登录的 BI 地址，例如
https://demo.guandata.com - 登录方式：选择登录方式，可选「用户名密码登录」或「直接输入 Token」，详细可参考 登录方式
- Domain（选择用户名密码登录时需要配置）：多租户/私有化部署时使用的域标识，一般用户直接回车留空，CLI 会自动探测；如果你的管理员明确告知了 Domain，请按其填写
- Login ID（选择用户名密码登录时需要配置）：登录账号
- Password（选择用户名密码登录时需要配置）：登录密码
登录成功后，Token 会自动保存到本机，后续命令无需重复登录。
登录方式
方式一：账号密码登录
获取账密步骤：
账号密码可登录 BI 环境获取，点击右上角头像可查看登录账号，若不清楚登录密码，请联系管理员获取。
登录成功页面：
方式二：Token 登录
获取 Token 步骤：
- 在浏览器中打开并登录 BI 系统
- 在 BI 页面任意空白处右键，点击「检查」（Chrome/Edge）或「检查元素」（Firefox），打开开发者工具
- 切换到「应用」（Application）标签页
- 在左侧「存储 > Cookie」中点击当前 BI 域名
- 找到名为
uidToken的 Cookie，复制其 Value 列的值，即为登录 Token
登录成功页面：
查看登录状态
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。
问题二：提示未登录或认证失败
-
查看状态
guancli auth status -
重新登录
guancli auth login
问题三：Token 过期
如果使用用户名密码登录，并保存了密码，工具会尝试自动重新登录。
如果使用 Token 登录，或没有保存密码，需要重新执行：
guancli auth login
问题四：GuanCLI 是否有 BI 版本依赖
基本无硬性依赖，核心功能（如卡片读取、数据集读取、表单操作等）在 BI 7.x 即可使用。
少数 API 可能依赖较新版本，例如「超级应用初始化」目前依赖 BI 8.2 版本，在低版本环境调用时会存在调用失败的可能性。如遇到此类情况，建议升级 BI 至对应版本后重试。