--- title: 命令 --- # 命令 命令是 CLI 的核心组成部分。每个命令都有一个名称、描述、选项和参数。您可以使用命令来执行特定的任务或操作。 ## 基础用法 ```ts const cli = Cli() .scriptName("foo-cli") .description("一个简单的 CLI") .version("1.0.0") .command("foo", "一个 foo 命令") .on("foo", (ctx) => { console.log("It works!"); }) .parse(); ``` 这将创建一个名为 `foo-cli` 的 CLI 应用程序,其中包含一个名为 `foo` 的命令。当用户运行 `foo-cli foo` 时,CLI 将输出 "It works!"。 ## 可选描述 描述参数是可选的。如果你不需要记录命令,可以省略它: ```ts const cli = Cli() .scriptName("foo-cli") .description("一个简单的 CLI") .version("1.0.0") .command("foo", { // 无描述,直接传递选项 flags: { output: { type: String, description: "输出文件", }, }, }) .on("foo", (ctx) => { console.log("It works!"); }) .parse(); ``` 或者,你也可以使用带有描述的传统语法: ```ts const cli = Cli() .scriptName("foo-cli") .description("一个简单的 CLI") .version("1.0.0") .command("foo", "一个 foo 命令", { flags: { output: { type: String, description: "输出文件", }, }, }) .parse(); ``` ## 别名 ### 概述 命令别名允许用户使用替代名称来调用命令。这对于提供更短或更直观的命令名称很有用。 ### 单个别名 你可以使用字符串为命令定义单个别名: ```ts const cli = Cli() .scriptName("foo-cli") .description("一个简单的 CLI") .version("1.0.0") .command("foo", "一个 foo 命令", { alias: "f", }) .on("foo", (ctx) => { console.log("It works!"); }) .parse(); ``` 现在 `foo-cli foo` 和 `foo-cli f` 都会输出 "It works!"。 ### 多个别名 你可以使用数组为命令定义多个别名: ```ts const cli = Cli() .scriptName("foo-cli") .description("一个简单的 CLI") .version("1.0.0") .command("foo", "一个 foo 命令", { alias: ["f", "bar", "baz"], }) .on("foo", (ctx) => { console.log("It works!"); }) .parse(); ``` 现在 `foo-cli foo`、`foo-cli f`、`foo-cli bar` 和 `foo-cli baz` 都以相同的方式工作。 ### 实践示例 #### 示例:Git 风格的缩写 ```ts const cli = Cli() .scriptName("git") .command("status", "显示工作树状态", { alias: "st", }) .on("status", (ctx) => { console.log("在分支 main 上..."); }) .command("commit", "记录对存储库的更改", { alias: ["ci", "com"], }) .on("commit", (ctx) => { console.log("提交更改..."); }) .command("checkout", "切换分支或恢复文件", { alias: "co", }) .on("checkout", (ctx) => { console.log("检出中..."); }) .parse(); ``` 使用: ```sh $ git st $ git commit $ git ci $ git com $ git checkout $ git co ``` ## 子命令 你可以通过在命令名称中使用空格来定义子命令: ```ts const cli = Cli() .scriptName("foo-cli") .description("一个简单的 CLI") .version("1.0.0") .command("parent child", "一个子命令") .on("parent child", (ctx) => { console.log("子命令被调用了!"); }) .parse(); ``` ## 根命令 你可以定义一个根命令(没有名称的命令)来处理没有指定子命令时的情况: ```ts const cli = Cli() .scriptName("foo-cli") .description("一个简单的 CLI") .version("1.0.0") .command("", "根命令") .on("", (ctx) => { console.log("根命令被调用了!"); }) .parse(); ``` ## 参数 ### 通用 参数(也称为 _位置参数_)是与参数值相对应的名称。将参数视为变量名,将参数值视为与变量关联的值。 可以在 `parameters` 数组属性中定义参数,以便通过名称访问特定的参数。这对于编写更可读的代码、强制验证和生成帮助文档非常有用。 参数可以按照以下格式进行定义: - **必需参数**由尖括号表示(例如 ``)。 - **可选参数**由方括号表示(例如 `[parameter name]`)。 - **扩展参数**由 `...` 后缀表示(例如 `` 或 `[parameter name...]`)。 注意,必需参数**不能在可选参数之后**,扩展参数必须放在最后。 可以在 `ctx.parameters` 属性上使用驼峰命名法来访问参数。 示例: ```ts // $ node ./foo-cli.mjs a b c d const cli = Cli() .scriptName("foo-cli") .description("一个简单的 CLI") .version("1.0.0") .command("foo", "一个 foo 命令", { parameters: [ "", "[optional parameter]", "[optional spread...]", ], }) .on("foo", (ctx) => { ctx.parameters; // ^? ctx.parameters.requiredParameter; // => "a" ctx.parameters.optionalParameter; // => "b" ctx.parameters.optionalSpread; // => ["c", "d"] }) .parse(); ``` ### 结束标志 结束标志(`--`)(也称为 _选项结束符_)允许用户传递一部分参数。这对于将应该与其他参数分开解析的参数或看起来像选项的参数非常有用。 一个例子是 [`npm run`](https://docs.npmjs.com/cli/v8/commands/npm-run-script): ```sh $ npm run