# @finebi/finebi-cli 中文文档

规范地址：https://npmcn.com/package/%40finebi/finebi-cli/

版本：2\.0\.16
npm 元数据更新时间：2026-11-10T11:26:06.105Z
中文译文更新时间：2026-11-14T18:46:03.821Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40finebi/finebi-cli
原文对照：https://npmcn.com/package/%40finebi/finebi-cli/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：2.3 MB，295 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=18\.17
- 运行依赖：0 个
- 首次发布：2026-09-24T07:34:08.293Z
- 最新版本发布：2026-11-10T11:26:05.878Z
- 近 30 天下载量：4404（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

FineBI 动态能力命令行客户端.

## 安装

```sh
npm install @finebi/finebi-cli
```

也可以使用：`pnpm add @finebi/finebi-cli`、`yarn add @finebi/finebi-cli`、`bun add @finebi/finebi-cli`

## README

# FineBI 缩写

FineBI CLI是FineBI插件能力的动态命令行客户端. 它处理本地配置,用户名/密码登录,能力缓存, `--help/-h`,和 HTTP 命令转发.

矩阵选项将 JSON 数组作为参数, 例如 `--values '["上海","江苏"]'` 用于地理匹配。 CLI 解析数组并在发送请求前验证其项目计划; 逗号分隔的文本不是一个数组 .

## 更改日志

### 2.0.16 联合国

-   在远程任务前从连接的 FineBI 插件中检查管理过的 Agent Skill 更新 。 更新内容包括捆绑的CLI.

### 2.0.14 国家

-   在会话到期后修复 Web app 登录回流 .
-   发送请求前拒绝丢失的JSON数字并复制仪表盘过滤密钥.
-   在Web应用模板中添加树和数字范围控制. JSON过滤器覆盖和清除需要兼容的 FineBI HTTP 端点.
-   以混合滤镜实例更新捆绑的Skill,保存复合条件,发布仪表板候选查询,以及时间组标签. 这些仪表板能力需要兼容的服务器插件.

### 2.0.13 信息技术

-   更新 CLI并捆绑 Skill 版本元数据.

### 2.0.12 信息技术

-   将捆绑的"技能"更新到必要的检查后立即返回仪表板查询结果,将后续查询限制在会影响回答正确性的差距.

### 2.0.11 联合国

-   使用插件的密码认证端点来发布 Access 密钥,而不在当地保存会话符. 密码登录需要兼容的服务器插件并拒绝 `--no-access-key`。 。 。 .
-   在动态命令中包含服务器的读取/写入元数据 `--help --json` 输出.
-   更新捆绑的Skill指令发现和仪表盘查询指南,用于源选择,过滤,平面图和度量查询.

### 2.0.10 联合国

-   当 PATH 包含相冲突的可执行文件时, 固定 Windows 系统命令分辨率用于应用程序认证,配置权限,以及浏览器的授权.
-   添加现代网络应用布局及其示例配置.
-   对齐 Web app 过滤默认和清除行为,并在应用程序配置改变时自动重新启动Vite.
-   更新捆绑的"技能"用于仪表板搜索,查询结果和布局指导.

### 2.0.9 国家

-   在 npm 安装和升级时自动同步管理下的代理技能及其捆绑的CLI,保留本地编辑并备份更新的技能.
-   将表格页码和基于视图的部件加载到捆绑的网络应用模板中 .
-   在CLI帮助和被捆绑的"技能"中澄清命令发现和仪表板源选择.
-   隔离 `app auth` 来自 PC 浏览器单登录策略的会话 `OTHER` 终端,同时保留过期和Access密钥撤销。 需要服务器插件 1.0.45 或稍后; 重新运行 `app auth` 升级后.

### 2.0.8 (简体中文)

-   允许web应用过滤器通过发送一个空阵列来明确清除仪表盘控制默认值. FineBI 平台的 HTTP `widgets/query` 端点必须支持此协议; 仅升级 CLI 插件是不够的 .

### 2.0.7 国家

-   在软件包 README 中添加更改日志 .

### 2.0.6 联合国

-   添加 `app auth` 从认证的 CLI 配置导出一个开发会话到网络应用程序项目的 `.env.local`。这需要兼容的 FineBI 服务器插件.
-   简化网络应用程序开发代理以重用导出会话并报告过期或缺失认证.

### 2.0.5 (中文(简体) )

-   更新捆绑的Skill的网络应用工作流程,以便在浏览器无法控制时继续,并明确报告无法执行的浏览器检查.

### 2.0.4 国家

-   Pnpm 用于安装 Web app 依赖性, 当 pnpm 未安装时使用 npm .

## 安装

```powershell
npm install -g @finebi/finebi-cli --registry=https://registry.npmjs.org/
```

这个包包括CLI和完整 `finebi-cli-agent` 技术 联系服务人员获取 FineBI 服务器插件,并在连接到 FineBI 之前有一个管理员安装或启用.

关于五步安装、认证和核查流程,见捆绑的 [代理安装指南](https://npmcn.com/package/%40finebi/finebi-cli/agent-installation-guide.md)。 。 。 .

## 使用量

内置帮助总是可用的,不需要服务器配置、登录或能力更新:

```powershell
finebi-cli --help
finebi-cli --help --json
finebi-cli config set --help
finebi-cli auth login --help
finebi-cli capability refresh --help
finebi-cli version --help
finebi-cli config --help
finebi-cli auth --help
finebi-cli capability --help
finebi-cli app --help
```

动态资源帮助, 例如 `finebi-cli <resource> --help`,从 FineBI 能力缓存中加载。 登录自动刷新此缓存 :

```powershell
finebi-cli config set base-url http://localhost:37799/webroot/decision
finebi-cli auth login --username 1
finebi-cli version
finebi-cli --help
finebi-cli <resource> --help
finebi-cli <resource> <command> [options]
```

创建和检查本地动态网络应用项目而不连接 FineBI :

```powershell
finebi-cli app create --name sales-dashboard --path D:\work --layout cockpit
finebi-cli app inspect --path D:\work\sales-dashboard
```

`app create` 复制捆绑 `web-app` 模板,设置工程 npm 名称,并将模板版本记录在 `public/app-config.json`。它拒绝现有的目的地,不安装依赖性或运行工程脚本. `app inspect` 读取 JSON 对象并报告配置摘要 `configValidated: false` 财务报告和审定财务报表 `remoteValidated: false`可选 `--strict` 以 CLI 捆绑模板规则进行验证,该规则可能不符合自定义应用程序扩展名. 检查不是验收门;使用生成的项目测试,构建和真实的浏览器检查来验证应用程序.

`--layout` 接受 `overview` (违约), `workbench`或绿色 `cockpit` 设置。 Cockpit共享现有的 Cookie 查询和认证流程,其中可配置的 KPI/chart/表绑定,独立重试,以及自定义的取月器. 生成的 README 和 `examples/cockpit.config.json` 描述占位符绑定; 不捆绑商业数据或证书。 需要公布来源 `directoryEntryId` 和支持目录权限的平台 HTTP 端点; 失败的查询从不切换来源 .

使用 `--layout retail` 包括横向导航、KPI条和蓝/橙海图. `examples/retail.config.json` 包含占位符零售绑定;见生成的关于明确KPI和月标签格式的设计指南。 创建会让工程不受约束,也不会查询服务器 .

带有认证的 CLI 配置文件, 运行 `finebi-cli app auth --path D:\work\sales-dashboard --profile test` 以导出 FineBI 会话到项目 `.env.local`。此命令连接到 FineBI ,并需要一个支持的插件 `/api/bi-cli/dev-session`。它保存了其他嵌入设置,对照剖面图检查项目目标,保存实际过期,并只打印非机密元数据。 导出会话有账户的完整平台权限. 保持文件的隐私和版本控制之外.

命令成功后启动或重新启动 Vite 。 代理只重用提供的代号 。 缺失或过期会话产生 `AUTH_REQUIRED` 日志提示; 活动代理或用户运行 `app auth` 再次重新启动 Vite 。 该代理从不引用 CLI, 登录或打开浏览器 。 使用 CLI 软件 `auth login --browser` 以便在需要时获得访问密钥。 见生成 [认证指南](https://npmcn.com/package/%40finebi/finebi-cli/templates/web-app/docs/auth-and-deploy.md#%E6%9C%AC%E5%9C%B0%E5%BC%80%E5%8F%91) 财务报告和审定财务报表 [代理工作流程](https://npmcn.com/package/%40finebi/finebi-cli/templates/web-app/AGENTS.md#%E8%AE%A4%E8%AF%81%E4%B8%8E%E4%BA%A4%E4%BB%98)现有项目需要更新开发代理; `app auth` 不升级源文件.

运行 `finebi-cli capability refresh` 当后端命令改变时,缓存会过期,或者您想要强制重新装入.

当服务器提供时, 资源和命令帮助显示其详细描述, 文本和 `--json` 输出。 旧的缓存能力,没有描述,仍然有效。 服务器省略了没有启用命令的资源组;在升级插件后刷新能力以查看当前命令表面.

动态命令 `--help --json` 包含 `data.mutation` 与参数和反应计划一起显示的能力: `false` 表示只读和 `true` 意思是变异 缺失的元数据仍然缺失,而不是默认只读. 帮助可以显示已过期的缓存能力;当缓存状态不明时检查其有效性,并且跨任务重复使用有效的发现结果. 这个 [代理发现工作流程](https://npmcn.com/package/%40finebi/finebi-cli/skills/finebi-cli-agent/references/command-workflows.md#1-%E4%BD%BF%E7%94%A8%E8%A7%84%E5%88%99) 说明何时更新或读取完整的清单.

`capabilities` 仍然是兼容的别名 `capability refresh`,但执行和答复格式不变。 使用 `capability refresh` 在新工作流程中;别名不列在常见命令中.

`config set capability-ttl-ms <ms>` 适用于下一个更新能力。 已存在的缓存过期状态保持不变; 设置命令报告此信息, 并给出选定配置文件的更新命令 。 使用 `capability info` 检查当前过期.

JSON 文件输入拒绝在 JavaScript 解析/串行过程中,包括溢出和下行时,其小数值会发生变化的数值符. 使用命令的精密合同支持的值; 数字字符串只有在其计划允许时才被接受.

对于仪表板组件查询,使用可重复的内置过滤器或JSON文件(互为专属):

```powershell
finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --filter "合同付款类型=分期付款" --filter "是否已经交货=是" --page-size 5
finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --filter "日期=2026-11-05" --filter "门店=[]"
finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --filters-file filters.json --page-size 5
```

`--filter "门店=[]"` 清除当前查询的控件过滤器。 选择文字文本 `[]`,使用时 `--filters-file` 与 `{"门店":["[]"]}`. Scalar控制清除需要平台提供者的空阵列协议;在授权的查询副本中清除树,数程和复合控制. 检查 `queryContext.clearSupported`; 见 [仪表板数据合同](https://npmcn.com/package/%40finebi/docs/dashboard-command-design.md#73-dashboard-data)。 。 。 .

树倒放/ 列表控制( E)`controlType=TREE/TREE_LIST`使用嵌入式路径,例如 `{"省市":[["浙江","杭州"]]}`树上标记(`TREE_LABEL`)使用每个级别选择,例如 `{"省市":[["浙江","江苏"],[]]}`,当空的内数组离开该水平时,不限制。 数字范围/ 滑行器使用一个完整的对象, 例如 `{"流水":{"min":100,"max":null,"closeMin":true,"closeMax":false}}` 页:1 `[100,+∞)`。通过 `--filters-file`,加所有平面覆盖;内含 `--filter` 无法与文件合并 。 混合实例、日期格式和所有复合文字类型均载于 [技能过滤示例](https://npmcn.com/package/%40finebi/finebi-cli/skills/finebi-cli-agent/references/dashboard-query-workflow.md#22-%E8%BF%87%E6%BB%A4%E8%BE%93%E5%85%A5%E7%A4%BA%E4%BE%8B)。 。 。 .

使用复合过滤器 `--filters-file` 与 `{"组合":{"values":{"$.0":["上海"],"$.1.0":100}}}`从同一来源获取原生叶道和字形种类 `dashboard info` → `queryContext.compositeInputs`。保存的字段、运算符、和/或组合和过滤等值保持不变;省略的叶片保留所保存的值. `{"组合":[]}` 清除授权查询副本中的全部复合材料。 复合覆被仅适用于数据组件;所保存的条件树必须在64个级别内相合,计出根和叶. 任何过滤器 JSON 对象中的复制密钥都被拒绝 。 见 [投入合同](https://npmcn.com/package/%40finebi/docs/dashboard-command-design.md#73-dashboard-data)。 。 。 .

过滤名称来自 `dashboard info` 控制条目' `filterName`组合和交叉表格 `--page` 用于单行目标页。 交叉表格的额外使用 `--column-page` 用于一个基于单一的目标栏页。 双轴独立默认为 1; 指定双轴以保留其他位置, 例如 `--page 3 --column-page 2`。 。 。 . `--page-size` 控制行或每页组,包括页眉扩展的表格.

对于相继导航,请从上次成功中加减 1 `data.page` 或者说 `data.columnPage`检查 `hasNext/hasPrevious` 或者说 `hasColumnNext/hasColumnPrevious` 先说 重复每个独立查询的相同的过滤器,尺寸选择,页面大小和源头,并明确保留交叉表格的其他轴. 当查询条件发生变化时,在第1页重新开始.

普通表格在删除页码选项时查询首页。 标题扩展的表格在省略所有页码选项时保留其初始视图; 指定 `--page`, (中文(简体) ), `--column-page` 或者说 `--page-size` 请求使用已保存的扩展配置进行页化。 图表未页. 参数和结果细节在 [仪表板数据合同](https://npmcn.com/package/%40finebi/docs/dashboard-command-design.md#73-dashboard-data)。该平台必须提供“提供者pagination”合同;更新插件后刷新能力.

将临时字段选择改为:

```powershell
finebi-cli dashboard info --id <dashboardId>
finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --dimension-ids '["<dimensionDId>","<measureDId>"]' --filter "合同付款类型=分期付款"
finebi-cli dashboard data --id <dashboardId> --entry-id <entryId> --dimension-ids '[]'
```

使用 `entries[].queryFields[].dId` 地点 `selectable=true`; 这是一个组件本地密钥, 不是数据集 `fieldId` 或字段名称. `queryFields` 包含已禁用字段并报告已保存 `used` 旗帜。 奥米 `--dimension-ids` 以保留所保存的选择。 该列表是一份完整的维度和度量的白色列表:未列出的可选字段被禁用. 包含计量 dId 以明确保留其输出; 只选择度量会禁用可选择的维度 。 明确 `[]` 禁用所有可选择的尺寸和度量;详细表格返回无列或行。 现有过滤器仍然有效。 空输出列并不意味着本地 pagination 总计为 0 .

对于出版的仪表板,通过同样的 `--directory-entry-id` 改为 `dashboard info` 财务报告和审定财务报表 `dashboard data`,并使用源代码。 安装此 npm 包只更新客户端并捆绑 Skill 。 这些命令需要服务器插件和平台提供商支持完整的维度和度量白名单;插件直接依赖于维度选择和发布源API. 服务器更新后刷新能力 .

### 多种环境

通过登录其名称和地址来创建环境:

```powershell
finebi-cli auth login --profile test --base-url https://test.example.com/webroot/decision --browser
finebi-cli auth login --profile prod --base-url https://prod.example.com/webroot/decision --username admin --password-stdin
finebi-cli auth list
finebi-cli auth use test
finebi-cli capability info --profile prod
finebi-cli auth info --profile prod
finebi-cli config set timeout-ms 60000 --profile prod
finebi-cli auth logout --profile prod
finebi-cli auth remove prod
```

成功登录选择环境为默认; 添加 `--no-use` 以保留已存在的默认值。 登录到现有名称后, 除非被覆盖, 否则会重新使用其地址 。 一个新名字需要 `--base-url` 或者说 `FINEBI_BASE_URL` 永远不会继承另一个环境的特性。 认证失败使已有环境和默认不变 .

选择顺序是 `--profile` > 翻译: `FINEBI_PROFILE` > 保存默认值。 选项在命令之前或之后有效 。 普通命令从不创建缺失的环境或更改默认. 名字是区分大小写,1-64 ASCII字母/数字/下分数/连字符,从字母或数字开始. `auth list` 仅显示本地元数据,而不是实时认证检查。 JSON的回复确定选定环境 `meta.profile`。 。 。 .

每个环境都有单独的资质,连接设置和能力. 更改已保存 `base-url` 清除其证书和缓存。 临时 URL/ token 覆盖不会改变保存的配置; 不同的 URL 永远不会继承保存的证书 。 带有临时证书的请求获取引用能力,而不覆盖保存的缓存 。 明确的会话符号优先于已保存的 Access 密钥 .

`auth logout` 撤销所选环境保存的密钥并保留其连接设置 . `auth remove <name>` 财务报告和审定财务报表 `config clear --profile <name>` 只删除本地环境和缓存,而不取消服务器证书。 删除默认不自动选择另一个已保存的环境 。 持续的配置和登录操作使用所选保存的环境,而不是连接覆盖变量.

使用 `auth remove <name>` 删除本地环境. `config clear --profile <name>` 仍然是与不变的执行和响应格式相容的别名;它可以通过直接命令帮助获得,但从中省略 `config` 命令列表。 两个命令都没有撤销服务器密钥; 运行 `auth logout --profile <name>` 当需要撤销时.

现有的单环境配置作为 `default`;只读命令不重写。 多环境写入它同时保留其证书和默认的能力缓存. 见 [命令合同](https://npmcn.com/package/%40finebi/docs/commands/README.md#%E5%A4%9A%E7%8E%AF%E5%A2%83%E7%AE%A1%E7%90%86) 完全的行为.

## 访问密钥

密码登录向插件的服务器侧认证端点发送了证书,该端点应用了 FineBI 登录政策并返回了 CLI 访问密钥. 浏览器授权保存在批准后收到的密钥 。 商业命令使用 `X-BI-CLI-Access-Key`; 服务器也接受 `X-FineBI-CLI-Access-Key` 作为相容性别名.

-   密码登录总是发布访问密钥 . `--no-access-key` 被拒绝。 CLI 只存储 Access 密钥和用户名; 密码- login 会话令牌及其过期时从未写入到 `config.json`。 。 。 .
-   `auth info` 显示 `authMode` (单位:千美元)`access-key` 编号 : `session-token` 编号 : `none`并蒙上全权证书。 会话模式仍然可供明确临时使用 `--token` 请求.
-   `auth logout` 在清除本地证书前取消保存的密钥 。 失败撤销保存证书以重试 ; `--force` 允许在未确认服务器撤销的情况下进行本地清理.

这个 [认证合同](https://npmcn.com/package/%40finebi/docs/commands/README.md#access-key-%E8%A1%8C%E4%B8%BA) 定义发行、配置描述、标题、兼容性和失败行为。 本地证书存储描述于 [本地文件](https://npmcn.com/package/%40finebi/finebi-cli/#readme-local-files)。 。 。 .

```powershell
finebi-cli auth login --username 1
finebi-cli auth info
finebi-cli auth logout
finebi-cli auth logout --force
```

代理发现流程 :

```powershell
finebi-cli --help --json
finebi-cli config set base-url http://localhost:37799/webroot/decision
finebi-cli auth login --from-env
finebi-cli system command-index --json
finebi-cli <resource> <command> --help --json
finebi-cli <resource> <command> [options] --json
```

`system command-index` 返回整个命令表面,作为按资源组合的压缩索引(`[write]` 标记突变, `[creates]` 附加标记资源创建;输出范围为8KB). 从它开始,而不是列举所有资源的帮助,然后打开 `--help` 只为你实际引用的命令.

对于复杂的基于文件的资源,不要期望命令帮助包含一个完整的源示例. `widget template` 返回按图表类型和情景选择的部件 JSL 源模板; `dashboard template` 返回带有指定占位符和可变合同的 Dashboard JS DSL 示例脚本。 他们 `add` 财务报告和审定财务报表 `update` 命令接受 JS DSL 源文件。 其它资源可能仍然会根据其动态命令帮助曝光可写作的JSON模板.

## 代理技能

安装捆绑 `finebi-cli-agent` 技能输入您的代理目录 :

```powershell
finebi-cli install-skill --list
finebi-cli install-skill --agents codex,cursor
```

运行 `finebi-cli install-skill` 在交互式终端中选择代理。 非交互式使用需要 `--agents`。支持的身份证是 `claude-code`, (中文(简体) ), `codex`, (中文(简体) ), `dsh`, (中文(简体) ), `cursor`, (中文(简体) ), `gemini-cli`, (中文(简体) ), `github-copilot`, (中文(简体) ), `opencode`, (中文(简体) ), `cline`, (中文(简体) ), `windsurf`, (中文(简体) ), `workbuddy`, (中文(简体) ), `trae`, (中文(简体) ), `trae-cn`, (中文(简体) ), `openclaw`, (中文(简体) ), `roo`,以及 `qwen-code`自定义 `CODEX_HOME`, (中文(简体) ), `CLAUDE_CONFIG_DIR`, (中文(简体) ), `DSH_HOME`, (中文(简体) ), `WORKBUDDY_HOME`,以及 `XDG_CONFIG_HOME` 目录得到尊重。 用于深搜索机,使用 `finebi-cli install-skill --agents dsh`; 技能安装到 `~/.dsh/skills` 默认,或 `<DSH_HOME>/skills` 何时 `DSH_HOME` 已经设定.

用于 WorkBuddy, 使用 `finebi-cli install-skill --agents workbuddy`; 技能安装到 `~/.workbuddy/skills` 默认,或 `<WORKBUDDY_HOME>/skills` 何时 `WORKBUDDY_HOME` 已经设定。 设定 `WORKBUDDY_HOME` 以匹配您 WorkBuddy 安装所用的配置根.

技能安装是本地的,不需要服务器连接或证书. 它复制了包含在这个已安装的npm版本中的Skill,包括它自己的CLI运行时间. 安装后恢复您的代理或刷新其技能 。 没有安装记录, npm 安装会使代理目录不受影响; 选择代理目录 `install-skill` 先说.

要更新, 安装最新的 CLI 软件包 :

```powershell
npm install -g @finebi/finebi-cli@latest --registry=https://registry.npmjs.org/
```

无 `postinstall` 在其记录的路径上同步管理的技能,包括自定义代理根,即使其环境变量不再设定. 被删除的"技能"没有被重新创建,没有被记录的"技能"也没有被采纳. 本地编辑保存. 同步错误不会使 CLI 安装失败 。 使用 `--foreground-scripts` npm 以查看同步结果;如果安装脚本被禁用(例如,与 `--ignore-scripts`),或重试,运行 `finebi-cli install-skill --agents codex,cursor` 手动. 刷新技能或更新后重新启动代理 .

在一次性安装了具有服务器同步功能的Skill后,它在远程任务前检查已配置的FineBI插件,再利用成功检查1小时. 一个相容的插件可以更新所设置的被管理技能,包括其捆绑的CLI. 所下载的CLI在本地运行,因此使用一个可信任的FineBI服务器并更喜欢HTTPS. 更新后,开始新的对话来加载更新后的规则. 本地编辑仍然受到保护.

安装记录使用绝对路径. 如果一个更古老的安装记录了相对的Agent root,自动同步报告而不猜测其位置. 运行 `install-skill` 一次从原始的工作目录 与原始代理环境 更新该记录.

相同的设施保持不变。 未修改管理的技能自动备份和更新。 没有记录的校验和的本地编辑和安装被保存,命令报告安装不完整. 要用备份明确取代它们:

```powershell
finebi-cli install-skill --agents codex --replace
```

备份存储于 `~/.finebi-cli/skill-backups/`; 安装记录在 `~/.finebi-cli/installation.json`。命令保存其他记录,不更改认证或连接配置。 斯克特跟随上面的发现流,并将动态指令帮助作为能力刷新后真理的来源.

## 产出

FineBI CLI 将两个观众放在心上:

-   人气内置命令默认打印简洁文本.
-   代理和脚本集成可以添加 `--json` 得到完整的JSON信封.
-   动态业务指令默认情况下会使用后端能力显示提示来进行人可读输出.
-   动态商业命令可以使用 `-f, --format` 对于由命令形状支持的显示格式.
-   `--json` 具有相对于显示格式的优先级,并总是返回完整的 JSON 信封.

`capability refresh` (另见: `capabilities`)默认打印资源/命令计数并获取/过期时间。 它保留了完整的清单 `--json`,保存输出和缓存。 瞬间连接获取本地缓存未变的报告 。 成功的更新回复包括 `meta.capabilityCache` 与 `cached`, (中文(简体) ), `fetchedAt` 和无效 `expiresAt`; TTL 设置响应保留 `data.key/value` 并添加通知 `meta.capabilityTtl`。 。 。 .

大型反应在到达呼叫者之前可以缩小(所有三种反应都是CLI-侧式的——它们是 从命令参数中剥去, 并且从未转发到插件 :

-   `--select <paths>` 将响应投放到逗号分隔的点路径(阵列使用索引, 譬如说. `data.dsl,warnings,errors.0.message`) (中文(简体) ). 输出总是JSON并保持 `ok` 编号 : `command`· ; 一个未知的路径会因可用的顶级密钥而响亮而失败,而不是打印部分结果.
-   `--max-chars <n>` 将长输出的头部和尾部保留在明显的去向标记上 (总/出自字符数加上如何获得全文). 盖子包含:标记 算上它,所以截断的输出不会超过 `n` 字符键.
-   `--save <path>` 写入完整的 JSON 信封(预计何时) `--select` 人类 渲染是丢失的,所以文件总是保持完整的响应),并只打印一个简短的摘要: `ok` 编号 : `command` 编号 : `saved` 编号 : `chars` 编号 : `warnings`。 。 。 . `--save` 胜过 `--max-chars` (内容提要) 已经很小; 写入报告失败 `INVALID_ARGUMENT` 用路径代替堆栈跟踪.

一个失败的命令永远不会被预测( 它 `data` 无效, 因此投影会隐藏真实错误 后面 `Unknown path(s)`(三); `--select` 意味着 JSON 输出,包括针对其自身的参数错误. 失败的命令仍然保存到 `--save` 已存在——文件持有失败信封,所以 脚本消费者从不读取之前的一次跑步的一则乏味的成功.

```powershell
finebi-cli dashboard dsl --id <id> --select data.dsl,warnings
finebi-cli dashboard bean --id <id> --save temp/board.json
finebi-cli subject info --id <id> --json --max-chars 8000
```

对人类友好的默认:

```powershell
finebi-cli version
finebi-cli config get
finebi-cli auth info
finebi-cli capability info
finebi-cli config clear
finebi-cli auth logout
finebi-cli capability clear-cache
```

结构化产出 :

```powershell
finebi-cli version --json
finebi-cli config get --json
finebi-cli auth info --json
finebi-cli capability info --json
finebi-cli <resource> <command> [options] --json
```

动态显示格式 :

```powershell
finebi-cli <resource> <command> [options] -f auto
finebi-cli <resource> <command> [options] -f table
finebi-cli <resource> <command> [options] -f expanded
finebi-cli <resource> <command> [options] -f csv
```

动态形状是 `record-list`, (中文(简体) ), `detail`, (中文(简体) ), `tabular-preview`,以及 `generic`。Java 能力元数据只声明形状和默认格式 `auto`. Node.js 使这些形状从响应数据中通用化,保存返回的信息而不是硬编码商业命令名称或命令特定列.

环境登录 :

```powershell
$env:FINEBI_BASE_URL="http://localhost:37799/webroot/decision"
$env:FINEBI_USERNAME="1"
$env:FINEBI_PASSWORD="your-password"
finebi-cli auth login --from-env
```

成功登录还试图刷新动态能力缓存. 如果刷新失败, 登录仍然成功, 且 CLI 打印一个警告 `finebi-cli capability refresh` 作为后续行动.

浏览器授权登录 :

```powershell
finebi-cli auth login --browser
```

此打印一个相同的服务器确认 URL 和代码到 stderr 。 打开URL并确认代码;当浏览器没有签名时,授权页面会重新定向到平台登录,登录后返回. CLI只发送浏览器授权请求字段,并在批准后保存返回的Access密钥;它不会向授权端点发送现有的本地证书.

通过 stdin 管道密码 :

```powershell
echo your-password | finebi-cli auth login --username 1 --password-stdin
```

## 本地文件

-   配置 : `%USERPROFILE%\.finebi-cli\config.json`
-   能力缓存 : `%USERPROFILE%\.finebi-cli\capabilities.json`
-   命名的环境缓存 : `%USERPROFILE%\.finebi-cli\capabilities-profile-<hex-encoded-name>.json` (单位:千美元)`default` 用途 `capabilities.json`) (中文(简体) ).

多种环境 `config.json` 存储 `schemaVersion: 2`, (中文(简体) ), `currentProfile` (可取消)和a `profiles` 对象按环境名称键。 写作以短命为序 `config.json.lock` 并解剖地替换配置文件。 30秒后锁定等待时间被关闭, 并报告一个错误而不修改文件 .

拒绝同时登录同一环境 `config.json.login-<hex-encoded-name>.lock`;不同的环境可能同时登录. 操作结束后,锁会被放出. 如果一个进程被强制终止并留下了锁后,在手动移除该锁文件之前,验证自有操作已经停止.

密码不被CLI所坚持. 保存的会话令牌和访问密钥在 `config.json`;它们没有被加密在休息。 在POSIX上, CLI 将目录限制为 `0700` 打开文件 `0600`在 Windows 上,它试图去除继承的ACL,并授予当前用户,System和管理员的访问权限;失败发出安全警告. 保护此目录及其备份 .

## 常见问题

### @finebi/finebi-cli 是什么？

FineBI 动态能力命令行客户端\.

### 如何安装 @finebi/finebi-cli？

在项目目录运行 npm install @finebi/finebi-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 finebi-cli，可以用 npx finebi-cli 直接运行。

### @finebi/finebi-cli 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/finebi\_\_finebi-cli 是否存在。

### @finebi/finebi-cli 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @finebi/finebi-cli 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=18\.17。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @finebi/finebi-cli 可以商用吗？

@finebi/finebi-cli 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @finebi/finebi-cli 的下载量有多少？

根据 npm 官方下载统计，@finebi/finebi-cli 在 2026/10/15 – 2026/11/13 这 30 天内被下载 4,404 次，日均约 147 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @finebi/finebi-cli 还在维护吗？

最新版本 2\.0\.16 发布于 2026/11/10（4 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/09/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。