# @drizzle-team/brocli 中文文档

规范地址：https://npmcn.com/package/%40drizzle-team/brocli/

版本：0\.12\.1
npm 元数据更新时间：2026-09-04T17:46:25.718Z
中文译文更新时间：2026-11-12T20:13:49.424Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40drizzle-team/brocli
原文对照：https://npmcn.com/package/%40drizzle-team/brocli/?lang=original
项目主页：https://github.com/drizzle-team/brocli
源码仓库：https://github.com/drizzle-team/brocli

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

- 包体积（解压后）：345 kB，8 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- 首次发布：2024-06-14T10:38:58.973Z
- 最新版本发布：2026-09-04T17:46:25.314Z
- 近 30 天下载量：131838416（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：32（近 12 个月 2 个）

## 中文简介

现代型式安全型建立国家领导机构的方法

## 安装

```sh
npm install @drizzle-team/brocli
```

也可以使用：`pnpm add @drizzle-team/brocli`、`yarn add @drizzle-team/brocli`、`bun add @drizzle-team/brocli`

## README

# 布罗克利

用 TypeScript 或 JavaScript 构建 CLI 的现代类型安全方式  
以 [滴水队](https://drizzle.team/)

```ts
import { command, string, boolean, run } from "@drizzle-team/brocli";

const push = command({
  name: "push",
  options: {
    dialect: string().enum("postgresql", "mysql", "sqlite"),
    databaseSchema: string().required(),
    databaseUrl: string().required(),
    strict: boolean().default(false),
  },
  handler: (opts) => {
    ...
  },
});

run([push]); // parse shell arguments and run command
```

### 为什么?

Brocli是用来解决我们在建设过程中遇到的挑战 [滴入外科手术](https://orm.drizzle.team/) 生成和运行 SQL 计划迁移的 CLI 同伴 :

-   [x] 明确、直接和可发现的API
-   [x] 在验证中构建的已打入的选项( 参数)
-   [x] 跨命令重复使用选项(或选项集)的能力
-   [x] 变形器钩子将运行时配置消耗从命令业务逻辑中解开
-   [x] `--version`, (中文(简体) ), `-v` 作为字符串或回调
-   [x] 在命令之前/ 之后运行常见内容的命令钩
-   [x] 明确的全球通路
-   [x] 可检验性,我们最重要的部分 移动不突破
-   [x] 主题, 简单的 API 到样式全局/ 命令帮助
-   [x] 消除道克漂移的 Docs 生成 API

### 通过实例学习

如果你需要 API 引用 - [看这里](https://npmcn.com/package/%40drizzle-team/brocli/#readme-api-reference),此实例列表 意思是成为英雄的零 让你学会布洛克利

带有位置参数的简单回声命令 :

```ts
import { run, command, positional } from "@drizzle-team/brocli";

const echo = command({
  name: "echo",
  options: {
    text: positional().desc("Text to echo").default("echo"),
  },
  handler: (opts) => {
    console.log(opts.text);
  },
});

run([echo])
```

```bash
~ bun run index.ts echo
echo

~ bun run index.ts echo text
text
```

打印版本为 `--version -v`数字 :

```ts
...

run([echo], {
  version: "1.0.0",
);
```

```bash
~ bun run index.ts --version
1.0.0
```

版本接受 async 回调, 供您在必要时在打印 cli 版本前做任何 io :

```ts
import { run, command, positional } from "@drizzle-team/brocli";

const version = async () => {
  // you can run async here, for example fetch version of runtime-dependend library

  const envVersion = process.env.CLI_VERSION;
  console.log(chalk.gray(envVersion), "\n");
};

const echo = command({ ... });

run([echo], {
  version: version,
);
```

# API 参考

[**`command`**](https://npmcn.com/package/%40drizzle-team/brocli/#readme-command)

-   [`command → name`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-command-name)
-   [`command → desc`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-command-desc)
-   [`command → shortDesc`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-command-shortDesc)
-   [`command → aliases`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-command-aliases)
-   [`command → options`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-command-options)
-   [`command → transform`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-command-transform)
-   [`command → handler`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-command-handler)
-   [`command → help`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-command-help)
-   [`command → hidden`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-command-hidden)
-   [`command → metadata`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-command-metadata)

[**`options`**](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options)

-   [`string`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options-string)
-   [`boolean`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options-boolean)
-   [`number`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options-number)
-   [`enum`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options-enum)
-   [`positional`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options-positional)
-   [`required`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options-required)
-   [`alias`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options-alias)
-   [`desc`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options-desc)
-   [`default`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options-default)
-   [`hidden`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options-hidden)

[**`run`**](https://npmcn.com/package/%40drizzle-team/brocli/#readme-run)

-   [`string`](https://npmcn.com/package/%40drizzle-team/brocli/#readme-options-string)

布罗克利 **`command`** 声明有:  
`name` - 命令名称,将列在 `help`  
`desc` - 可选描述,将在命令中列出 `help`  
`shortDesc` - 可选的简短描述,将在所有命令/所有子命令中列出 `help`  
`aliases` - 命令名称别名  
`hidden` - 隐藏命令的旗帜 `help`  
`help` - 命令帮助文本或召回以动态配置打印帮助文本  
`options` - 拟解析并提供给 `transform` 或者说 `handler`  
`transform` - 可选钩子,在处理器前调用以修改 CLI 参数  
`handler` - 使用任意一种类型调用 `options` 或者说 `transform` 参数, 运行命令业务逻辑的地方  
`metadata` - 文件生成流程的可选元信息

`name`, (中文(简体) ), `desc`, (中文(简体) ), `shortDesc` 财务报告和审定财务报表 `metadata` 提供给文件生成步骤

```ts
import { command, string, boolean } from "@drizzle-team/brocli";



const push = command({
  name: "push",
  options: {
    dialect: string().enum("postgresql", "mysql", "sqlite"),
    databaseSchema: string().required(),
    databaseUrl: string().required(),
    strict: boolean().default(false),
  },
  transform: (opts) => {
  },
  handler: (opts) => {
    ...
  },
});
```

```ts
import { command } from "@drizzle-team/brocli";

const cmd = command({
  name: "cmd",
  options: {
    dialect: string().enum("postgresql", "mysql", "sqlite"),
    schema: string().required(),
    url: string().required(),
  },
  handler: (opts) => {
    ...
  },
});

```

### 选项构建器

初始构建器功能 :

-   `string(name?: string)` - 将选项定义为字符串类型选项,该选项要求将数据传递为 `--option=value` 或者说 `--option value`
    
    -   `name` - cli 参数中通过选项的名称  
        如果没有指定,则默认为此选项的密钥  
        : 警告: - 不得包含 `=` 字符,不包含 `--help`, (中文(简体) ),`-h`, (中文(简体) ),`--version`, (中文(简体) ),`-v` 并每个命令独有  
        : speech balloon: - 将自动前缀 `-` 如果有一个角色长, `--` 如果更长  
        如果您想要在多字符名上只设置单个连字符作为前缀 - 只需在其中指定名称 : `string('-longname')`
-   `number(name?: string)` - 将选项定义为数字类型选项,其中要求将数据传递为 `--option=value` 或者说 `--option value`
    
    -   `name` - cli 参数中通过选项的名称  
        如果没有指定,则默认为此选项的密钥  
        : 警告: - 不得包含 `=` 字符,不包含 `--help`, (中文(简体) ),`-h`, (中文(简体) ),`--version`, (中文(简体) ),`-v` 并每个命令独有  
        : speech balloon: - 将自动前缀 `-` 如果有一个角色长, `--` 如果更长  
        如果您想要在多字符名上只设置单个连字符作为前缀 - 只需在其中指定名称 : `number('-longname')`
-   `boolean(name?: string)` - 将选项定义为布尔类型选项,它要求将数据传递为 `--option`
    
    -   `name` - cli 参数中通过选项的名称  
        如果没有指定,则默认为此选项的密钥  
        : 警告: - 不得包含 `=` 字符,不包含 `--help`, (中文(简体) ),`-h`, (中文(简体) ),`--version`, (中文(简体) ),`-v` 并每个命令独有  
        : speech balloon: - 将自动前缀 `-` 如果有一个角色长, `--` 如果更长  
        如果您想要在多字符名上只设置单个连字符作为前缀 - 只需在其中指定名称 : `boolean('-longname')`
-   `positional(displayName?: string)` - 将选项定义为一个位置类型选项,它要求在命令后通过数据,作为 `command value`
    
    -   `displayName` - cli 参数中通过选项的名称  
        如果没有指定,则默认为此选项的密钥  
        : 警告: - 不消耗起始于

扩展名 :

-   `.alias(...aliases: string[])` - 定义选项的别名
    
    -   `aliases` - cli 参数中通过选项的别名  
        : 警告: - 不得包含 `=` 字符,不包含 `--help`, (中文(简体) ),`-h`, (中文(简体) ),`--version`, (中文(简体) ),`-v` 并每个命令独有  
        : speech balloon: - 将自动前缀 `-` 如果有一个角色长, `--` 如果更长  
        如果您希望在多字符别名上只使用单个连字符作为前缀——只需在其中指定别名: `.alias('-longname')`
-   `.desc(description: string)` - 定义要显示在 `help` 命令
    
-   `.required()` - 根据需要设置选项, 这意味着如果 cli 参数中不存在错误, 应用程序将打印出错误
    
-   `.default(value: string | boolean)` - 设置选项的默认值, 如果在 cli 参数中不存在的话, 选项将被指定给它
    
-   `.hidden()` - 设置为隐藏的选项 - 选项将被省略 `help` 命令
    
-   `.enum(values: [string, ...string[]])` - 将字符串的值限制在此处指定之一
    
    -   `values` - 允许的enum值
-   `.int()` - 确保数字是一个整数
    
-   `.min(value: number)` - 指定数字允许的最小值
    
    -   `value` - 允许的最小值  
        : 警告: - 不限制默认值
-   `.max(value: number)` - 指定数字允许的最大值
    
    -   `value` - 允许的最大值  
        : 警告: - 不限制默认值

### 创建处理器

通常,你可以写 处理器右在 `command()` 函数,但可能存在一些情况,您需要单独定义您的处理器.  
对于这种情况,你会想 推断类型 `options` 那将会是 传入你的操作器.  
你可以使用它来做 `TypeOf` 类型 :

```Typescript
import { string, boolean, type TypeOf } from '@drizzle-team/brocli'

const commandOptions = {
    opt1: string(),
    opt2: boolean('flag').alias('f'),
    // And so on... 
}

export const commandHandler = (options: TypeOf<typeof commandOptions>) => {
    // Your logic goes here...
}
```

或者通过使用 `handler(options, myHandler () => {...})`

```Typescript
import { string, boolean, handler } from '@drizzle-team/brocli'

const commandOptions = {
    opt1: string(),
    opt2: boolean('flag').alias('f'),
    // And so on... 
}

export const commandHandler = handler(commandOptions, (options) => {
    // Your logic goes here...
});
```

### 定义命令

要定义命令, 使用 `command()` 函数 :

```Typescript
import { command, type Command, string, boolean, type TypeOf } from '@drizzle-team/brocli'

const commandOptions = {
    opt1: string(),
    opt2: boolean('flag').alias('f'),
    // And so on... 
}

const commands: Command[] = []

commands.push(command({
    name: 'command', 
    aliases: ['c', 'cmd'],
    desc: 'Description goes here',
    shortDesc: 'Short description'
    hidden: false,
    options: commandOptions,
    transform: (options) => {
        // Preprocess options here...
        return processedOptions
    },
    handler: (processedOptions) => {
        // Your logic goes here...
    },
    help: () => 'This command works like this: ...',
    subcommands: [
        command(
            // You can define subcommands like this
        )
    ]
}));
```

参数:

-   `name` - 以 cli 参数搜索命令的名称  
    : 警告: - 决不能从 `-` 字符,等于\[`true`, (中文(简体) ), `false`, (中文(简体) ), `0`, (中文(简体) ), `1`(对大小写不敏感),每个命令集独有
    
-   `aliases` - 以克力克搜索命令的别名  
    : 警告: - 决不能从 `-` 字符,等于\[`true`, (中文(简体) ), `false`, (中文(简体) ), `0`, (中文(简体) ), `1`(对大小写不敏感),每个命令集独有
    
-   `desc` - 用于显示命令的说明 `help` 命令
    
-   `shortDesc` - 要显示的命令的简短描述 `help` 命令
    
-   `hidden` - 设置命令为隐藏 - 如果 `true`中,命令将被省略 `help` 命令
    
-   `options` - 包含命令选项的对象 `string` 财务报告和审定财务报表 `boolean` 函数
    
-   `transform` - 预处理选项的可选功能,然后将其传递给处理器  
    : 警告: - 返回类型变异处理器输入类型
    
-   `handler` - 函数,在选项解析成功时执行  
    : 警告: - 如果您的命令没有子命令, 必须在场  
    如果命令有子命令但没有处理器, 此命令的帮助将被调用, 而不是处理器
    
-   `help` - 函数或字符串,当需要帮助时会执行或打印此命令  
    :警告: - 如果通过,将流行于主题 `commandHelp` 事件
    
-   `subcommands` - 命令的子命令  
    : 警告: - 命令不能有子命令和 `positional` 选项同时
    
-   `metadata` - 您想要附加到命令中供以后用于 docs 生成步骤的任何数据
    

### 运行命令

定义命令后,您需要执行 `run` 启动命令执行的函数

```Typescript
import { command, type Command, run, string, boolean, type TypeOf } from '@drizzle-team/brocli'

const commandOptions = {
    opt1: string(),
    opt2: boolean('flag').alias('f'),
    // And so on... 
}

const commandHandler = (options: TypeOf<typeof commandOptions>) => {
    // Your logic goes here...
}

const commands: Command[] = []

commands.push(command({
    name: 'command', 
    aliases: ['c', 'cmd'],
    desc: 'Description goes here',
    hidden: false,
    options: commandOptions,
    handler: commandHandler,
}));

// And so on...

run(commands, {
    name: 'mysoft',
    description: 'MySoft CLI',
    omitKeysOfUndefinedOptions: true,
    argSource: customEnvironmentArgvStorage,
    version: '1.0.0',
    help: () => {
        console.log('Command list:');
        commands.forEach(c => console.log('This command does ... and has options ...'));
    },
    theme: async (event) => {
        if (event.type === 'commandHelp') {
            await myCustomUniversalCommandHelp(event.command);

            return true;
        }

        if (event.type === 'unknownError') {
            console.log('Something went wrong...');

            return true;
        }

        return false;
    },
    globals: {
        flag: boolean('gflag').description('Global flag').default(false)
    },    
    hook: (event, command, globals) => {
        if(event === 'before') console.log(`Command '${command.name}' started with flag ${globals.flag}`)
        if(event === 'after') console.log(`Command '${command.name}' succesfully finished it's work with flag ${globals.flag}`)
    }
})
```

参数:

-   `name` - 名字用来引用你的cli申请.  
    用于打印使用示例的主题,例如:  
    `app do-task --help` 结果 `Usage: app do-task <positional> [flags] ...`  
    默认 : `undefined`
    
-   `description` - 描述你的应用  
    用于主题,例如:  
    `myapp --help` 结果
    

```
MyApp CLI

Usage: myapp [command]...
```

默认 : `undefined`

-   `omitKeysOfUndefinedOptions` - 确定是否将未定义的选项传递到转换和处理器的旗帜  
    默认 : `false`
    
-   `argSource` - 环境中数组参数的位置  
    : 警告 : - 此存储的前两个项将被忽略, 因为它们通常包含可执行和执行的文件路径  
    默认 : `process.argv`
    
-   `version` - 用于打印应用程序版本的字符串或处理器  
    : 警告 : - 如果通过, 将流行于主题的版本事件
    
-   `help` - 用于打印应用程序全局帮助的字符串或处理器  
    :警告: - 如果通过,将流行于主题 `globalHelp` 事件
    
-   `theme(event: BroCliEvent)` - 用于自定义各种事件所打印信件的函数  
    返回 :  
    `true` | `Promise<true>` 如果您认为已处理的事件  
    `false` | `Promise<false>` 重定向到默认主题
    
-   `globals` - 可在 `hook`  
    : 警告: - 位置不允许进入 `globals`  
    :警告: - 名称和别名不得与命令选项相重叠
    
-   `hook(event: EventType, command: Command, options: TypeOf<typeof globals>)` - 用于在每个命令前后执行代码的函数 `transform` 财务报告和审定财务报表 `handler` 执行
    

### 其他职能

-   `commandsInfo(commands: Command[])` - 简化命令集的表述  
    可用于生成文件
    
-   `test(command: Command, args: string)` - 用指定参数测试命令的行为  
    : 警告: - 如果命令已经 `transform`但是,它会被调用 `handler` 不会
    
-   `getCommandNameWithParents(command: Command)` - 获得父命令名称的子命令名称
    

## 国 际

单位 `BroCLI`,命令不一定是第一个论据,相反,它可能以任何顺序通过.  
为了让这个可能,蜂窝,在命令之前通过的选择应该有明确的价值,即使它是一面旗帜: `--verbose true <command-name>` (不适用于保留的旗帜:\[ `--help` | `-h` | `--version` | `-v`)  
选项在严格模式下解析,这意味着拥有任何未识别的选项会导致出错.

## 常见问题

### @drizzle-team/brocli 是什么？

现代型式安全型建立国家领导机构的方法

### 如何安装 @drizzle-team/brocli？

在项目目录运行 npm install @drizzle-team/brocli，或使用 pnpm add / yarn add / bun add。

### @drizzle-team/brocli 支持 TypeScript 吗？

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

### @drizzle-team/brocli 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @drizzle-team/brocli 可以商用吗？

@drizzle-team/brocli 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @drizzle-team/brocli 的下载量有多少？

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

### @drizzle-team/brocli 还在维护吗？

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