【免费下载链接】usageA specification for CLIs项目地址https://gitcode.com/gh_mirrors/usage/usage点击查看免费下载写 CLI 的人大多有过这种烦恼帮助信息写在代码里补全脚本另写一份文档手工维护三者经常对不上。Usage 就是为此而生的CLI 规范CLI specification你用一份 KDL 文件描述命令、标志flags、参数和帮助文本然后由它统一生成 shell 补全、--help输出、Markdown 参考文档、man page甚至 TypeScript / Python 类型化 SDK。一句话概括Define your CLI once. Generate the tools around it.一、问题CLI 的接口契约散落各处回想一下 HTTP 服务的世界OpenAPI 让接口文档、客户端、Mock 都来自同一份定义。而 CLI 呢帮助文本 → 散落在代码字符串里补全脚本 → 手写或者用框架自动生成但无法自定义文档站 → 复制粘贴版本漂移调用方的代码 → 没有类型信息全靠猜结果是同一份接口信息被维护了 N 份而且没有任何工具能检查这次改动是不是 breaking change。Usage 的思路和 OpenAPI 完全一致先把 CLI 的接口写成一份规范其余产物全部从规范派生。二、什么是 Usage三个身份一份规范Usage 同时是三样东西详见 README.md身份说明一份可移植的 KDL 规范*.usage.kdl文件描述命令树、标志、参数、配置、补全️一条命令行工具usage负责 lint、生成补全/文档/manpage/SDK、检查接口 diff⚙️一个 Rust 框架usage-rs从 struct 派生类型化解析器并导出可移植规范规范语言选的是KDL——读起来像配置文件嵌套起来像 XML。语法非常直觉看这个最小示例取自 docs/spec/index.mdbin mycli about Process project files flag -f --force helpOverwrite existing output flag -v --version helpPrint the CLI version arg dir helpThe directory to use // 尖括号 必填 arg [file] helpThe file to read // 方括号 可选file表示必填位置参数[file]表示可选keyvalue属性补充元数据——十行就能把一个小工具的接口讲清楚。三、核心能力一份规范能生成什么1. 解析、帮助与 shell 补全规范描述的就是接口语义哪个标志全局global#true、哪个取值有枚举choices、子命令如何嵌套。lib/src/complete/ 下实现了 bash、zsh、fish、PowerShell、Nu 五种 shell 的补全逻辑全部从同一份规范派生天然保持一致。2. 文档与 man page 一键生成usage generate markdown --file mycli.usage.kdl --out-file reference.md usage generate manpage --file mycli.usage.kdl --out-file mycli.1参考实现见 cli/src/cli/generate/markdown.rs 与 cli/src/cli/generate/manpage.rs。接口变了重新生成即可文档漂移问题从根上消失。3. 类型化 SDK给调用你 CLI 的代码用如果别的产品要通过子进程调用你的 CLIUsage 可以生成TypeScript / Python SDK见 lib/src/sdk/调用方拿到的是类型化客户端而不是拼字符串——这正是 OpenAPI 生态里代码生成客户端在 CLI 世界的对应物。4. 配置解析与优先级规则规范可以声明 flag 由配置文件、环境变量或默认值回退支撑优先级恒定为CLI flag 环境变量 配置文件 默认值实现位于 config/src/resolve.rs。相关规则详见 docs/spec/resolution.md。5. 命令效果声明为 AI Agent 时代做准备比较有前瞻性的是effect字段声明一条命令会对外部世界做什么effect含义read只读检查幂等write创建/修改状态destructive可能删除或不可逆覆盖值得二次确认AI 编码助手拿到这份规范后可以直接获得一份只读命令白名单而不用每次都问用户。相关测试见 conformance/tests/effect.rs。6. 接口 diffCLI 版的 breaking change 检查usage diff可以比较两版规范在发布前发现移除标志、改名参数这类破坏性变更实现见 cli/src/cli/diff.rs。这对维护多版本 CLI 的团队非常实用。四、四条接入路径总有一条适合你docs/index.md 把用户分成了四类每类都有明确入口新建 Rust CLIstruct #[usage(...)]派生代码即规范docs/rust/quickstart.md已有 CLI从 clap、Cobra、kong、urfave 等框架导出规范应用代码一行不改docs/spec/integrations.mdCobra 转换实现见 integrations/cobra/convert.goShell 脚本在注释里声明参数Usage 帮你解析并注入环境变量docs/cli/scripts.md纯规范工作流手写 KDL用 CLI 生成一切产物docs/guide/getting-started.md项目还内置了外部工具实测benches/external/ 目录里有fd、starship、tokei的真实规范与损失清单losses诚实展示哪些接口特性规范能覆盖、哪些还差一点——这种透明度很少见。五、快速上手5 分钟体验完整闭环# 安装三选一 brew install usage # 或 mise use -g usage cargo install usage-cli --locked # 假设已写好 mycli.usage.kdl usage lint mycli.usage.kdl # 校验规范 usage generate completion zsh mycli --file mycli.usage.kdl --install # 装补全 usage generate markdown --file mycli.usage.kdl --out-file reference.md规范语法与完整示例在 docs/spec/index.md各节点cmd、flag、arg、config、complete……的字段级参考在 docs/spec/reference/。想看真实世界的规范长什么样仓库自带了不少examples/kitchen-sink.usage.kdl、examples/with-examples.usage.kdl以及从 mise 等复杂工具导出的 benches/mise.usage.kdl。六、为什么值得认真对待✅单一事实源帮助、补全、文档、SDK 永远同步✅生态互通KDL 规范与语言/框架无关Rust、Go预览版见 go/argv/、脚本都能消费它✅可验证lint抓错误diff抓破坏性变更✅面向 AI 协作effect声明让 Agent 安全地自动执行命令✅测试严谨conformance/tests/ 下有上百个一致性测试corpus/ 提供结构化用例集如果你的 CLI 正在被用户、脚本、Agent 从多个入口调用一份规范不再是锦上添花而是接口工程的基本盘——就像每个严肃的 API 都该有一份 OpenAPI 一样。下一步建议从你最头疼的那个 CLI 开始试着手写一份 20 行的usage.kdl运行一次usage lint和usage generate markdown你就会明白这份规范的价值。赞分享【免费下载链接】usageA specification for CLIs项目地址https://gitcode.com/gh_mirrors/usage/usage点击查看免费下载相关推荐深入理解 CommonMark为什么我们需要统一的 Markdown 标准深入理解 CommonMark为什么我们需要统一的 Markdown 标准 在当今数字化时代 CommonMark 作为 Markdown 的标准化规范正开发工具解锁非Pixel设备专属功能Pixelify Google Photos模块深度解析与实战指南解锁非Pixel设备专属功能Pixelify Google Photos模块深度解析与实战指南 你是否曾羡慕Pixel用户能够享受Google Photos中移动开发为什么你需要一个gRPC图形界面客户端BloomRPC深度解析为什么你需要一个gRPC图形界面客户端BloomRPC深度解析 还在为复杂的gRPC调试而烦恼吗BloomRPC作为一款备受推崇的gRPC图形界面客户端为开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/15 20:32:42 · 阅读 1.2k 为什么你的 CLI 需要一份规范？深入理解 Usage——CLI 界的 OpenAPI 完全解读
【免费下载链接】usageA specification for CLIs项目地址https://gitcode.com/gh_mirrors/usage/usage点击查看免费下载写 CLI 的人大多有过这种烦恼帮助信息写在代码里补全脚本另写一份文档手工维护三者经常对不上。Usage 就是为此而生的CLI 规范CLI specification你用一份 KDL 文件描述命令、标志flags、参数和帮助文本然后由它统一生成 shell 补全、--help输出、Markdown 参考文档、man page甚至 TypeScript / Python 类型化 SDK。一句话概括Define your CLI once. Generate the tools around it.一、问题CLI 的接口契约散落各处回想一下 HTTP 服务的世界OpenAPI 让接口文档、客户端、Mock 都来自同一份定义。而 CLI 呢帮助文本 → 散落在代码字符串里补全脚本 → 手写或者用框架自动生成但无法自定义文档站 → 复制粘贴版本漂移调用方的代码 → 没有类型信息全靠猜结果是同一份接口信息被维护了 N 份而且没有任何工具能检查这次改动是不是 breaking change。Usage 的思路和 OpenAPI 完全一致先把 CLI 的接口写成一份规范其余产物全部从规范派生。二、什么是 Usage三个身份一份规范Usage 同时是三样东西详见 README.md身份说明一份可移植的 KDL 规范*.usage.kdl文件描述命令树、标志、参数、配置、补全️一条命令行工具usage负责 lint、生成补全/文档/manpage/SDK、检查接口 diff⚙️一个 Rust 框架usage-rs从 struct 派生类型化解析器并导出可移植规范规范语言选的是KDL——读起来像配置文件嵌套起来像 XML。语法非常直觉看这个最小示例取自 docs/spec/index.mdbin mycli about Process project files flag -f --force helpOverwrite existing output flag -v --version helpPrint the CLI version arg dir helpThe directory to use // 尖括号 必填 arg [file] helpThe file to read // 方括号 可选file表示必填位置参数[file]表示可选keyvalue属性补充元数据——十行就能把一个小工具的接口讲清楚。三、核心能力一份规范能生成什么1. 解析、帮助与 shell 补全规范描述的就是接口语义哪个标志全局global#true、哪个取值有枚举choices、子命令如何嵌套。lib/src/complete/ 下实现了 bash、zsh、fish、PowerShell、Nu 五种 shell 的补全逻辑全部从同一份规范派生天然保持一致。2. 文档与 man page 一键生成usage generate markdown --file mycli.usage.kdl --out-file reference.md usage generate manpage --file mycli.usage.kdl --out-file mycli.1参考实现见 cli/src/cli/generate/markdown.rs 与 cli/src/cli/generate/manpage.rs。接口变了重新生成即可文档漂移问题从根上消失。3. 类型化 SDK给调用你 CLI 的代码用如果别的产品要通过子进程调用你的 CLIUsage 可以生成TypeScript / Python SDK见 lib/src/sdk/调用方拿到的是类型化客户端而不是拼字符串——这正是 OpenAPI 生态里代码生成客户端在 CLI 世界的对应物。4. 配置解析与优先级规则规范可以声明 flag 由配置文件、环境变量或默认值回退支撑优先级恒定为CLI flag 环境变量 配置文件 默认值实现位于 config/src/resolve.rs。相关规则详见 docs/spec/resolution.md。5. 命令效果声明为 AI Agent 时代做准备比较有前瞻性的是effect字段声明一条命令会对外部世界做什么effect含义read只读检查幂等write创建/修改状态destructive可能删除或不可逆覆盖值得二次确认AI 编码助手拿到这份规范后可以直接获得一份只读命令白名单而不用每次都问用户。相关测试见 conformance/tests/effect.rs。6. 接口 diffCLI 版的 breaking change 检查usage diff可以比较两版规范在发布前发现移除标志、改名参数这类破坏性变更实现见 cli/src/cli/diff.rs。这对维护多版本 CLI 的团队非常实用。四、四条接入路径总有一条适合你docs/index.md 把用户分成了四类每类都有明确入口新建 Rust CLIstruct #[usage(...)]派生代码即规范docs/rust/quickstart.md已有 CLI从 clap、Cobra、kong、urfave 等框架导出规范应用代码一行不改docs/spec/integrations.mdCobra 转换实现见 integrations/cobra/convert.goShell 脚本在注释里声明参数Usage 帮你解析并注入环境变量docs/cli/scripts.md纯规范工作流手写 KDL用 CLI 生成一切产物docs/guide/getting-started.md项目还内置了外部工具实测benches/external/ 目录里有fd、starship、tokei的真实规范与损失清单losses诚实展示哪些接口特性规范能覆盖、哪些还差一点——这种透明度很少见。五、快速上手5 分钟体验完整闭环# 安装三选一 brew install usage # 或 mise use -g usage cargo install usage-cli --locked # 假设已写好 mycli.usage.kdl usage lint mycli.usage.kdl # 校验规范 usage generate completion zsh mycli --file mycli.usage.kdl --install # 装补全 usage generate markdown --file mycli.usage.kdl --out-file reference.md规范语法与完整示例在 docs/spec/index.md各节点cmd、flag、arg、config、complete……的字段级参考在 docs/spec/reference/。想看真实世界的规范长什么样仓库自带了不少examples/kitchen-sink.usage.kdl、examples/with-examples.usage.kdl以及从 mise 等复杂工具导出的 benches/mise.usage.kdl。六、为什么值得认真对待✅单一事实源帮助、补全、文档、SDK 永远同步✅生态互通KDL 规范与语言/框架无关Rust、Go预览版见 go/argv/、脚本都能消费它✅可验证lint抓错误diff抓破坏性变更✅面向 AI 协作effect声明让 Agent 安全地自动执行命令✅测试严谨conformance/tests/ 下有上百个一致性测试corpus/ 提供结构化用例集如果你的 CLI 正在被用户、脚本、Agent 从多个入口调用一份规范不再是锦上添花而是接口工程的基本盘——就像每个严肃的 API 都该有一份 OpenAPI 一样。下一步建议从你最头疼的那个 CLI 开始试着手写一份 20 行的usage.kdl运行一次usage lint和usage generate markdown你就会明白这份规范的价值。赞分享【免费下载链接】usageA specification for CLIs项目地址https://gitcode.com/gh_mirrors/usage/usage点击查看免费下载相关推荐深入理解 CommonMark为什么我们需要统一的 Markdown 标准深入理解 CommonMark为什么我们需要统一的 Markdown 标准 在当今数字化时代 CommonMark 作为 Markdown 的标准化规范正开发工具解锁非Pixel设备专属功能Pixelify Google Photos模块深度解析与实战指南解锁非Pixel设备专属功能Pixelify Google Photos模块深度解析与实战指南 你是否曾羡慕Pixel用户能够享受Google Photos中移动开发为什么你需要一个gRPC图形界面客户端BloomRPC深度解析为什么你需要一个gRPC图形界面客户端BloomRPC深度解析 还在为复杂的gRPC调试而烦恼吗BloomRPC作为一款备受推崇的gRPC图形界面客户端为开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考