跳到正文

命令行参考

用统一的调用格式记录子命令、选项、默认值、退出状态以及可复制的示例。

写清命令的入口和作用

标题使用真实的子命令名称。给出一行调用格式,并说明在哪个目录和终端中运行。若依赖初始化或配置文件,写明如何满足条件。短选项和长选项一起记录,例如 -o 与 --output。

doc-index build [--output <file>] [--include-drafts]

这个示例工具用方括号标记可省略的部分,用尖括号标记需要替换的值。可复制示例使用实际的示例值。

doc-index build --output ./search-index.json

记录每个选项的效果

选项值省略后的行为
--output <file>输出文件路径使用配置文件指定的路径
--include-drafts无参数开关根据当前配置判断是否包含草稿

支持重复参数、互斥选项或位置参数时,给出有效组合和执行顺序。配置路径相对于工作目录还是配置文件目录,会影响复制后的结果,需要在例子前说明。

区分输出和退出状态

说明命令产生哪些文件,标准输出适合人读还是供后续工具解析。可用于脚本的状态码写在可查找的位置。破坏已有数据或需要独立环境的操作,应在命令前交代影响和验证办法。维护者验证帮助文本、命令和文档表格后,可用审阅清单检查示例完整性。