# @grantjs/cli 中文文档

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

版本：1\.29\.0
npm 元数据更新时间：2026-11-10T14:42:03.811Z
中文译文更新时间：2026-11-17T07:03:47.470Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40grantjs/cli
原文对照：https://npmcn.com/package/%40grantjs/cli/?lang=original
项目主页：https://github.com/grant-js/grant#readme
源码仓库：https://github.com/grant-js/grant

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

- 包体积（解压后）：553 kB，28 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=18\.0\.0
- 运行依赖：2 个
- 首次发布：2026-03-11T21:07:58.658Z
- 最新版本发布：2026-11-10T14:42:02.891Z
- 近 30 天下载量：5388（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：70（近 12 个月 70 个）

## 中文简介

Grant CLI - 配置文件、 REST API 和打字生成

## 安装

```sh
npm install @grantjs/cli
```

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

## README

# @ granjs/ cli (英语)

授予CLI用于配置文件,REST API访问和打字生成. 代理和脚本应该使用 `grant api` 或者说 `grant <resource> <verb>` 与 `--output json` (或 `GRANT_*` 环境变量).

## 安装

```bash
pnpm add -g @grantjs/cli
# or
npm install -g @grantjs/cli
```

## 图标概览

| 命令 | 说明 |
| --- | --- |
| `grant version` | 显示 CLI 版本 (S)`-j, --json` 为JSON) |
| `grant help` 编号 : `grant --help` | 显示帮助 |
| `grant start` | 交互式设置(API URL, 认证, 配置文件, 范围); 化名 : `grant setup` |
| `grant whoami` | 显示已认证的呼叫者( N)`GET /api/me`(中文(简体) ) |
| `grant api <method> <path>` | 使用已解析的配置文件调用 REST 路径 |
| `grant <resource> <verb>` | 从 OpenAPI (例如) 命名 REST 命令. `grant users list`(中文(简体) ) |
| `grant generate-types` | 生成工程范围d `ResourceSlug` 财务报告和审定财务报表 `ResourceAction` 类型脚本( 使用所选配置文件) |
| `grant config path` | 打印配置文件的路径 |
| `grant config list` | 列表配置文件为默认 |
| `grant config show` | 显示配置文件的配置摘要( 无秘密) |
| `grant config set <key>` | 设置配置文件的配置值(见下文) |

所有使用配置的命令都接受 **`-p, --profile <name>`** (或 `GRANT_PROFILE`。API 命令也接受 `--output json|text` (JSON当stdout不是TTY).

环境: `GRANT_API_URL`, (中文(简体) ), `GRANT_ACCESS_TOKEN`, (中文(简体) ), `GRANT_CLIENT_ID`, (中文(简体) ), `GRANT_CLIENT_SECRET`, (中文(简体) ), `GRANT_SCOPE_TENANT`, (中文(简体) ), `GRANT_SCOPE_ID`, (中文(简体) ), `GRANT_ORIGIN_VERIFY`。旗帜胜于嵌入,潜入于配置文件.

```bash
export GRANT_PROFILE=ci
grant whoami --output json
grant users list --output json
grant api post /api/roles --body '{"name":"Reviewer"}'
```

* * *

## 设置 : `grant start`

交互式流程 :

1.  **授予 API 基础 URL** — 默认 : `http://localhost:4000` (或现值.
2.  **认证方法** – 说吧 – **会议** (浏览器登录)或 **API 密钥**。 。 。 .
3.  **配置文件名称** — 此配置的名称( 如 ) . `default`, (中文(简体) ), `staging`) (中文(简体) ). 覆盖 `--profile <name>` 跳过提示.
4.  **会话流量** - 签入 **电子邮件** (电子邮件+密码)或 **GitHub 图像** (浏览器OAuth). 然后选择账户/组织(如果适用)/项目.
5.  **API 密钥流量** - 客户身份(UUID)、客户秘密(min 32 chars)、范围租户(UUID)`accountProject` 编号 : `organizationProject`),范围ID(例如. `accountId:projectId` 或者说 `organizationId:projectId`) (中文(简体) ).
6.  **生成类型的默认输出** ——可选路径(如:. `./src/grant-types.ts`) (中文(简体) ). 留空给 `./grant-types.ts`。 。 。 .

配置被保存到平台配置目录(例如. `~/.config/grant/config.json` 在Linux/macOS上。 第一个创建的配置文件成为默认; 用 `grant config set default-profile <name>`。 。 。 .

### 会话认证

-   **电子邮件** – 您需要电子邮件和密码; CLI 呼叫 Grant API 登录端点, 并存储返回的访问和刷新令牌 .
-   **GitHub 图像** – CLI 启动本地 HTTP 临时服务器, 并打开您的浏览器到 Grant API 的 GitHub OAuth URL , 并加一个 `redirect` 改为 `http://localhost:<port>`。在您与 GitHub 签约后, API 用一次性代码重定向到 URL 。 CLI 交换密码以通过 `POST /api/auth/cli-callback`。在 URL 中不发送任何令牌;代码是单用和短寿命(如60秒). API 只接受 `localhost` (或 `127.0.0.1`作为这种流动的取向.

**实例:**

```bash
grant start
grant start --profile staging
```

* * *

## 生成类型 : `grant generate-types`

装入所选配置文件, 在需要时将 API 密钥交换为一个令牌, 获取工程范围的资源和权限, 并写入 TypeScript 文件 `ResourceSlug` 财务报告和审定财务报表 `ResourceAction` 常数.

-   **`-o, --output <path>`** - 输出文件( 默认: profile ) `generateTypesOutputPath` 或者说 `./grant-types.ts`) (中文(简体) ).
-   **`--dry-run`** - 打印不写将生成的东西.
-   **`-p, --profile <name>`** - 要使用的配置文件( 默认: 默认配置文件) .

**实例:**

```bash
grant generate-types
grant generate-types --profile staging -o ./src/grant-types.ts
grant generate-types --dry-run
```

* * *

## 配置 : `grant config`

### `grant config path`

打印配置文件的路径(无配置文件).

### `grant config list`

列出配置名称并标记默认值.

### `grant config show`

显示配置文件的配置摘要(API URL, 认证方法, 范围, 生成类型输出; 无秘密) .

-   **`-p, --profile <name>`** — 要显示的配置文件( 默认: 默认配置文件) .

### `grant config set`

设置配置文件的值 。 使用 **`-p, --profile <name>`** 以目标配置文件(默认:默认配置文件).

| 子命令 | 说明 |
| --- | --- |
| `grant config set api-url <url>` | 设置 Grant API 基础 URL( 如. `http://localhost:4000`(中文(简体) ) |
| `grant config set auth-method <session | api-key>` | 设定认证方法 |
| `grant config set credentials` | 设置 API 密钥和范围(见下文选项) |
| `grant config set scope` | 只设定选中的项目范围 |
| `grant config set generate-types-output <path>` | 设置默认输出路径 `grant generate-types` (空出为清 |
| `grant config set origin-verify [secret]` | 设定 `x-origin-verify` 何时 `apiUrl` 是原始 API 来源 |
| `grant config set default-profile <name>` | 设定何时使用哪个配置文件 `--profile` 删除 |

**全权证书备选方案** (所需一切资源) `credentials`:

-   `--client-id <id>` — API 密钥客户端标识( UUID)
-   `--client-secret <secret>` - API 密钥客户端( min 32 个字符)
-   `--scope-tenant <tenant>` – 说吧 – `accountProject` 或者说 `organizationProject`
-   `--scope-id <id>` -比如说. `accountId:projectId` 或者说 `organizationId:projectId`

**范围选项** (计: `scope`:

-   `--tenant <tenant>` – 说吧 – `accountProject` 或者说 `organizationProject`
-   `--scope-id <id>` - 范围标识字符串

**实例:**

```bash
grant config set api-url http://localhost:4000
grant config set api-url http://localhost:4000 --profile staging
grant config set credentials --client-id <uuid> --client-secret <secret> --scope-tenant organizationProject --scope-id <orgId>:<projectId>
grant config set scope --tenant organizationProject --scope-id <orgId>:<projectId>
grant config set generate-types-output ./src/grant-types.ts
grant config set default-profile staging
```

* * *

## 发展(从单一雷波)

```bash
pnpm --filter @grantjs/cli run build
node packages/@grantjs/cli/dist/index.mjs version
# or link globally: from packages/@grantjs/cli run pnpm link --global
```

**互动 TUI :** 运行 `grant start` (和任何提示) 在一个真正的终端 所以过程有一个TTY。 运行通过IDE"跑"或者在CI中往往没有sdin,提示不会奏效.

**联合国** [赠款CLI](https://github.com/grant-js/grant/blob/main/docs/integration/cli.md) 在官方的文档.

**出版时间:** 见 [发 言](https://npmcn.com/package/%40grantjs/cli/RELEASE.md) 用于版本和 npm 发布( Changesets).

**测试 :**

```bash
pnpm --filter @grantjs/cli test
pnpm --filter @grantjs/cli test:watch
```

* * *

## 常见问题

### @grantjs/cli 是什么？

Grant CLI - 配置文件、 REST API 和打字生成

### 如何安装 @grantjs/cli？

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

### @grantjs/cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @grantjs/cli 支持 ESM 还是 CommonJS？

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

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

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

### @grantjs/cli 可以商用吗？

@grantjs/cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

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

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

### @grantjs/cli 还在维护吗？

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

