Yargs 中如何优雅地为默认命令添加描述

在 Node.js 命令行工具开发中，Yargs 是一个非常流行的参数解析库。许多开发者在使用 Yargs 时会遇到一个常见需求：如何在不影响默认命令行为的情况下，为默认命令添加描述信息。

问题背景

当开发者使用 Yargs 构建 CLI 工具时，通常会有这样的需求：

1. 保持默认命令的行为（即不覆盖默认命令）
2. 同时希望为默认命令添加描述信息
3. 确保 demandCommand() 等验证功能正常工作

直接使用 .usage() 或定义默认命令可能会带来一些副作用，比如意外覆盖了默认命令的实现。

解决方案

Yargs 提供了灵活的方式来满足这一需求。最推荐的做法是：

.usage(`$0 <command>

这里是你的CLI工具详细描述

可以包含多行内容`)

这种方式的优势在于：

1. 不会影响默认命令的实际行为
2. 可以自由添加多行描述文本
3. 保持了 Yargs 原有的命令验证功能
4. 生成的帮助信息结构清晰

实际效果示例

使用上述方法后，生成的帮助信息会呈现如下结构：

工具名称 <command>

这里是你的CLI工具详细描述

可以包含多行内容

Commands:
  工具名称 foo  Foo命令描述

Options:
  --help     显示帮助信息 [boolean]
  --version  显示版本号 [boolean]

最佳实践建议

1. 保持描述简洁明了，控制在3-5行内
2. 第一行使用 <command> 表明需要子命令
3. 在描述中包含工具的主要功能和基本用法
4. 避免在描述中使用过于技术性的术语
5. 考虑添加简单的使用示例

通过这种方式，开发者可以在不干扰 Yargs 默认行为的前提下，为用户提供清晰的使用说明，提升 CLI 工具的整体用户体验。