Cmdabra

从声明性YAML和实现处理程序或方法对象构建命令行接口。

# cmdabra.yaml
name: project
description: Manage a project
commands:
  dependencies:
    description: Manage dependencies
    commands:
      update:
        description: Update one package
        aliases: [up]
        examples: [project dependencies update --package-name yaml]
        named-options:
          package-name:
            type: string
            required: true
            short: p

import { runCli } from '@jakobm/cmdabra';

await runCli('./cmdabra.yaml', {
  dependencies: {
    async update(namedOptions) {
      // The application owns behavior and output.
    },
  },
});

平面命令和嵌套命令映射到实现对象中的相同形状。Kebab-case命令名变成camelCase方法名和命名空间名，而Kebab-case选项名变成camelCase属性。叶子方法按照声明顺序接收位置参数，当声明命名选项时，后跟一个命名选项对象。字符串、布尔值、枚举和文件选项支持必需值、默认值、重复值、短标志、别名、环境回退和示例。 枚举选项要求非空 choices 列表。

使用 description 对于命令清单中显示的短文本。根或命令也可以声明多行 details;Cmdabra仅在可执行文件的帮助中显示这些详细信息，在其描述之后，在其参数和选项之前：

commands:
  report:
    description: Build a report
    details: |
      Reports include all matching records.

      Use filters to narrow the result.

没有子命令的CLI直接在根目录下声明其输入，并使用一个函数作为其实现：

name: search
description: Search files
named-options:
  pattern: { type: string, required: true, short: p }
  ignore-case: { type: boolean, short: i }

await runCli('./cmdabra.yaml', async (namedOptions) => {
  // namedOptions.pattern and namedOptions.ignoreCase
});

无命令配置可以声明 positional-arguments， named-options, examples;它的处理程序接收与其他叶子相同的位置参数优先、命名选项最后签名。具有子命令的配置或命令组可以声明 named-options，这是每一个后代叶子所继承的。位置参数仍然只有叶子，选择没有叶子的组仍然显示不完整组的帮助，而不是调用处理程序。

继承选项在完整的命令路径之后提供，与特定于叶子的选项一起：

name: project
named-options:
  config: { type: string, env-var: PROJECT_CONFIG }
commands:
  dependencies:
    named-options:
      format: { type: enum, choices: [text, json], default: text }
    commands:
      audit: {}

project dependencies audit --config project.yaml --format json

继承的选项名或短别名不得与同一命令路径上的另一个输入冲突。

每个选项名至少包含两个字符。任何选项类型都可以有一个可选的单字母 short 别名;别名在命令中是唯一的， -h 和 --help 为生成的帮助保留，以及 --cmdabra-complete， --cmdabra-completion, --cmdabra-install-completion 为shell完成保留。布尔短选项可以按任何顺序分组，因此 -Nap 等于 -N -a -p． 一个组只能包含布尔标志。字符串和枚举短选项使用单独的值，例如 -N -f data.json;附加的值，例如 -fdata.json 不支持。

命令声明有序输入 positional-arguments 和命名的输入 named-options． 位置参数总是必需的，并且必须声明 type: string， type: enum，或者 type: file． 枚举参数要求 choices.

所有位置参数必须位于所有选项之前。选项值是单独的令牌： --file data.json 支持，而 --file=data.json 不是。值可以以 -． 重复一个选项是错误的，除非它声明 repeatable: true。这个 -- 不支持选项结束标记。

环境退

一个非布尔的、不可重复的命名选项可以声明一个环境变量fallback：

named-options:
  file:
    type: file
    env-var: LEDLIGHT_FILE

显式命令行值优先，然后是非空的自动stdin default-stdin 文件选项，环境变量，最后 default． 环境值使用该选项的普通枚举验证和文件加载。声明的环境变量存在但为空是使用错误。不支持布尔和可重复选项 env-var 因为它们的字符串表示是不明确的。环境回退由shell工具组成，如direnv；Cmdabra本身不搜索或加载环境文件。

文件输入

一、 file 输入接受文件系统路径或 - stdin。Cmdabra在调用处理程序之前打开文件系统路径，因此丢失或不可读的文件是运行时错误。空文件和空显式stdin是有效的。 read-as 控制是否 content text（默认值）是 Buffer，或者 Readable 流:

named-options:
  input:
    type: file
    read-as: text # text, buffer, or stream
    default-stdin: true

处理程序接收内容及其来源：

export type FileInput<T> =
  | { source: 'file'; path: string; content: T }
  | { source: 'stdin'; content: T };

default-stdin: true 当未显式提供该选项且没有其他文件输入使用时，分配非空重定向stdin -． 每个可执行文件最多只能启用一个文件选项。目前支持自动stdin read-as: text 和 read-as: buffer； read-as: stream 必须使用explicit - 因为 stream 与 default-stdin: true 暂不支持。显式的 - 总是选择stdin，包括空的stdin，并且一次调用只能将stdin分配给一个文件输入。文件支持的流归Cmdabra所有，并且在处理程序确定之前保持可用。

过程的行为

runCli 从 process.argv． 对于带有命令的配置，空命令行显示root帮助；选择不带子命令的命令组将显示该命令组的帮助。当声明的输入允许时，无命令配置将一个空命令行传递给它的根处理程序。使用错误和生成的帮助被写入stderr并设置 process.exitCode 2。其他错误是与它们的堆栈和集合一起写入的 process.exitCode 为1。关闭的标准输出管道成功退出，而不是报告 EPIPE.

对于受控的进程内执行，传递 CliProcess 的第三个可选参数 runCli． 这个狭窄的、进程形的契约只涵盖命令参数、环境、标准流、退出代码和Cmdabra使用的立即退出行为；在node . js process 对象直接满足它。省略参数使用的是实际过程。

壳完成

每个Cmdabra CLI都提供全局 --cmdabra-complete 选择。Shell适配器传递一个以零为基础的当前单词索引，后面跟着所有标记的命令行单词，包括作为单词零的可执行文件。Cmdabra读取当前的YAML配置，并将匹配的候选者写入标准输出，每行一个。它完成嵌套命令和别名、位置和选项枚举选择、文件输入的文件系统路径以及继承和本地选项；不可重复的选项在使用后被省略。

每个Cmdabra CLI还提供了两个独立的选项，不需要额外的YAML或应用程序处理程序：

project --cmdabra-completion bash          # Print a Bash completion script.
project --cmdabra-install-completion bash  # Install it for the current user.
project --cmdabra-completion zsh           # Print a Zsh autoload completion file.
project --cmdabra-install-completion zsh   # Install it for the current user.
project --cmdabra-completion fish          # Print a Fish completion script.
project --cmdabra-install-completion fish  # Install it for the current user.

取代 project 配置了可执行文件 name，必须在 PATH． 在命令行开头使用一个shell参数传递任一管理选项(bash， zsh，或者 fish）. 这些框架选项适用于有或没有子命令的cli；否 completion 命令是保留的。

默认情况下，三个完成选项显示在生成的帮助中。要隐藏它们，设置 show-completion-options-in-help: false 在YAML配置的根目录下：

name: project
show-completion-options-in-help: false
commands:
  status:
    description: Show project status

这个布尔设置适用于根、命令组和叶子帮助，包括为使用错误打印的帮助。它只控制帮助可见性：所有三个选项都保留并可用，shell完成仍然建议使用它们。省略该设置或将其设置为 true 来展示它们。这个设置只允许在根目录下进行。

安装将创建父目录，并报告安装路径和shell设置说明。重新安装一个未修改的脚本不会改变它；标记为Cmdabra为该可执行文件和shell生成的脚本可以更新。现有的外部文件、目录和符号链接将被拒绝。安装过程不会编辑shell启动文件，也不会在安装npm包时自动运行。

Bash

Bash脚本安装为 <directory>/<name>，其中目录为：

• $BASH_COMPLETION_USER_DIR/completions 当 BASH_COMPLETION_USER_DIR 非空。
• $XDG_DATA_HOME/bash-completion/completions 当 XDG_DATA_HOME 非空。
• $HOME/.local/share/bash-completion/completions 否则。

与现代 bash-completion 在交互式shell中安装并启用，它的加载器根据需要发现这个文件。安装程序没有安装或激活 bash-completion，并且无法验证父shell的状态。打开一个新shell来获取集成。另外, source 安装的文件立即注册完成，包括在Bash设置中没有 bash-completion． 生成的适配器使用与Bash 3.2兼容的语法。

Zsh

Zsh脚本安装为 _<name> 在 $XDG_DATA_HOME/zsh/site-functions，或者 $HOME/.local/share/zsh/site-functions 当 XDG_DATA_HOME 为空或未设置。Zsh默认不搜索此目录。添加到 fpath 之前 现有的 compinit 把你的 .zshrc （使用安装程序打印的实际路径）：

fpath=("${XDG_DATA_HOME:-$HOME/.local/share}/zsh/site-functions" $fpath)
autoload -Uz compinit
compinit

如果shell框架已经调用 compinit，把 fpath 初始化前的加法。然后打开一个新的shell。如果现有的完成缓存缺少新命令，则使用 compinit -D.

生成的Zsh脚本是一个自动加载的完成文件 #compdef 头;把它放在 fpath 目录 _<name> 手动安装时。它不是一个可以直接从中获取源代码的脚本 .zshrc.

鱼

Fish脚本安装为 <name>.fish 在 $XDG_CONFIG_HOME/fish/completions，或者 $HOME/.config/fish/completions 当 XDG_CONFIG_HOME 为空或未设置。Fish通过它的默认值自动发现这个目录 fish_complete_path;不需要更改启动文件或额外的完成包。如果你自定义 fish_complete_path请把这个目录保存在里面。

安装后打开一个新shell，或者 source 安装程序显示的已安装文件，以便立即注册。对于手动安装，将生成的脚本保存为 <name>.fish 在同一个目录下。适配器使用Fish的令牌化命令行，并将候选生成委托给可执行程序，包括文件系统候选。它禁用了Fish的备用文件名建议，因此不相关的文件不会出现在命令或枚举补全中。

完成协议

完成引擎仍然是独立于shell的。所有三个适配器都将其shell的单词和当前单词索引转换为 --cmdabra-complete 请求。Zsh的集中 CURRENT 转换为从零开始的索引；Bash使用 COMP_CWORD． 鱼用 commandline 对光标之前的单词进行标记，并从当前标记之前的单词计算索引。保留包含空格的参数和候选参数。包含换行符的候选文件系统不能用基于行的协议表示，因此将被省略。

可执行文件在每次请求时读取其当前的YAML配置，因此配置更改在下一次完成时生效，而无需重新安装shell脚本。没有命令树嵌入到适配器中。所有配置的安装目录必须是绝对路径；空的环境变量被视为未设置。

打印稿合同

从YAML的真实源生成实现接口：

cmdabra generate-types cmdabra.yaml --output src/cmdabra.generated.ts

使用上下文类型和实现它 satisfies CmdabraImplementation． 当配置包含文件输入时，生成的模块也会导出 FileInput 对于需要命名运行时值的帮助程序。CI可以在运行前检测漂移 tsc：

cmdabra generate-types cmdabra.yaml --output src/cmdabra.generated.ts --check