# @common-grants/cli 中文文档

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

版本：0\.5\.0
npm 元数据更新时间：2026-10-27T16:15:25.337Z
中文译文更新时间：2026-11-10T12:24:25.801Z
软件包许可：CC0-1\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40common-grants/cli
原文对照：https://npmcn.com/package/%40common-grants/cli/?lang=original
项目主页：https://github.com/HHS/simpler-grants-protocol/tree/main/lib/cli#readme
源码仓库：https://github.com/HHS/simpler-grants-protocol

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

- 包体积（解压后）：739 kB，33 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.0\.0
- 运行依赖：11 个
- 首次发布：2025-02-06T03:20:08.063Z
- 最新版本发布：2026-10-27T16:15:24.943Z
- 近 30 天下载量：2773（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：36（近 12 个月 15 个）

## 中文简介

CLI 协议工具

## 安装

```sh
npm install @common-grants/cli
```

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

## README

# 常见赠款 CLI

普通Grants CLI (英语:`cg`)是一个与"通用Grants"协议合作的工具. 它简化了界定、实施和验证通用赠款API的程序.

> **说明**: 此软件包目前为α. 下文所描述的命令被嘲弄了执行,将在今后的发布中被全部功能所取代.

## 安装

```bash
# Install globally
npm install -g @common-grants/cli

# Or use with npx
npx @common-grants/cli <command>
```

## 使用量

查看可用的命令和选项 :

```bash
cg --help
```

输出 :

```
CommonGrants CLI tools

Options:
  -V, --version           output the version number
  -h, --help              display help for command

Commands:
  init [options]          Initialize a new CommonGrants project
  preview <specPath>      Preview an OpenAPI specification
  check                   Validate APIs and specifications
  compile <typespecPath>  Compile a TypeSpec file to OpenAPI
  help [command]          display help for command
```

### 初始化项目

从模板创建新的 CommonGrants 项目 :

```bash
# Initialize interactively
cg init

# List available templates
cg init --list

# Use a specific template
cg init --template custom-api
```

### 将类型编译为 OpenAPI

将 TypeSpec 文件编译为 OpenAPI 规格 :

```bash
cg compile spec.tsp
```

这是薄薄的包裹 `tsp compile` 命令并使用您的工程 `tspconfig.yaml` 用于确定输出格式的文件.

### 预览 OpenAPI 规格

使用 Swagger 界面预览 API 规格 :

```bash
# Preview a YAML file
cg preview openapi.yaml

# Preview a JSON file
cg preview openapi.json
```

### 验证 API 规格

对照 CommunityGrants 基础协议验证 API 规格 。 您可以选择指定特定协议版本来检查,或者提供一个路径来获取自己的基谱. 默认, `check spec` 使用与 CLI 捆绑的基协议的最新版本.

```bash
# Using the base protocol spec bundled with @common-grants/cli, uses the latest version by default
cg check spec openapi.yaml

# Using a specific protocol version
cg check spec openapi.yaml --protocol-version 0.4.0

# Using the path to a locally compiled base spec
cg check spec openapi.yaml --base <path-to-base-spec>
```

调查结果报告为错误或警告。 错误以退出码 1 失败命令 。 打印、标记警告 `(warning)`,而且命令仍然以退出代码 0 成功,因为一个路由 : `optional` 可能因履约而省略.

## 发展状况

此 CLI 正在积极开发中, 只支持以下命令 :

-   `cg init` 带有一组有限的模板
-   `cg compile`
-   `cg preview`
-   `cg check spec`

## 预期特点

以下例子说明了国家综合倡议的预期特点,但这些特点尚未执行,可能会有变化.

### 验证 API 执行

检查一个 API 执行是否符合其规格 :

```bash
# Basic validation
cg check api https://api.example.com spec.yaml

# Generate validation report
cg check api https://api.example.com spec.yaml --report json

# Validate with authentication
cg check api https://api.example.com spec.yaml --auth bearer:token
```

## 常见问题

### @common-grants/cli 是什么？

CLI 协议工具

### 如何安装 @common-grants/cli？

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

### @common-grants/cli 支持 TypeScript 吗？

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

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

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

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

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

### @common-grants/cli 可以商用吗？

@common-grants/cli 使用 CC0-1\.0 许可。作者放弃著作权，可不受限制地使用。以上为概括，不构成法律意见，请以许可原文为准。

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

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

### @common-grants/cli 还在维护吗？

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