命令行界面指南
Hacker News 摘要原标题：Command Line Interface Guidelines
命令行界面指南（Command Line Interface Guidelines，简称 CLIG）是一份开源指南，旨在帮助开发者编写更优秀的命令行程序。它将传统的 Unix 原则与现代软件开发的需求相结合。该指南由 Aanand Prasad（Docker Compose 共同创作者）、Ben Firshman（Replicate 联合创始人）、Carl Tashian 和 Eva Parish 等人共同编写。
设计哲学
编写优秀的命令行程序应当遵循以下核心原则：
以人为本的设计：传统的 Unix 命令多假设使用者是其他程序，更像编程语言中的函数。现代命令行工具虽然仍需支持脚本化，但应优先考虑人类用户的交互体验。
简单组件的协作：保持程序功能单一且接口清晰，通过标准输入输出、信号和退出码实现模块化协作。尽管现代通用脚本语言流行，但通过管道组合程序的能力依然至关重要。
跨程序的一致性：命令行约定已经形成了用户的肌肉记忆。尽可能遵循现有的参数、标志和环境变量模式，让工具变得可预测且易于上手。
信息量恰到好处：输出信息不足会让用户怀疑程序死机，信息过多则会淹没重点。开发者需要平衡清晰度与简洁度。
易于发现：虽然命令行通常依赖记忆，但好的设计可以引导用户。通过完善的帮助文本、示例、错误后的操作建议等手段，提升功能的发现效率。
对话式交互：用户连续运行命令、根据错误修改参数、探索系统状态的过程本质上是一种对话。程序应通过纠错建议、状态确认和干预确认来优化这种对话体验。
鲁棒性与同理心：程序不仅要内部稳定，还要让用户感觉到可靠。这包括处理意外输入、提供有意义的错误信息、避免打印恐怖的堆栈跟踪。开发者应当站在用户的角度解决问题，让工具使用起来令人愉悦。
有序的混乱：命令行世界充满不一致性。虽然鼓励遵循标准，但如果某个标准明显损害效率，开发者应当有意识地打破规则，追求更好的用户体验。
基础准则
解析与退出：使用成熟的命令行参数解析库处理标志和帮助文本。成功执行时返回零退出码，失败时返回非零。核心数据发送到 stdout，日志、消息和错误发送到 stderr。
帮助系统：支持 -h 和 --help 标志。在不带参数直接运行时显示简洁的帮助信息。帮助文本应优先展示常见的示例用法，并使用粗体标题提升扫描效率。如果用户输入了错误的子命令且能推测意图，应提供拼写建议。
文档规范：提供网页版文档以便搜索和分享，同时也应提供 man 页面或终端内的详细说明。网页链接可以嵌入帮助文本中。
输出设计
人类优先：当检测到输出目标是交互式终端（TTY）时，提供易读的格式；如果是管道或脚本调用，则保持稳定简洁。
机器可读：提供 --json 标志输出结构化数据，或使用 --plain 提供表格化文本，方便配合 grep 或 awk 使用。
状态反馈：当状态发生变化（如 git push 完成）时，明确告知用户发生了什么。提供查看当前系统状态的命令（如 status 命令）。
视觉增强：在不干扰阅读的前提下，可以使用 ASCII 艺术或图形符号增加信息密度。慎重使用颜色，且必须尊重 NO_COLOR 或 TERM=dumb 等环境设置，在非终端环境中禁用颜色和动画进度条。
长文本处理：输出大量内容时，如果检测到是交互式终端，建议自动调用 less 等分页器，配置参数通常建议为 less -FIRX。
参数与标志
优先使用标志：除了简单的多文件处理（如 rm），尽量使用带名称的标志而非位置参数，这样更具自述性且不易出错。
标志命名规范：提供完整长度的标志名，常用标志使用单字母缩写。遵循行业标准，例如 -f 表示强制，-v 表示版本或详细模式，-n 表示干拟执行（Dry Run），-q 表示静默模式。
安全处理敏感数据：严禁直接通过命令行标志传递密码或密钥，因为这会通过进程列表或 shell 历史记录泄露。应支持通过文件、环境变量或标准输入读取秘密。
交互交互性：仅在 TTY 环境下进行交互提问。提供 --no-input 标志供脚本使用。输入密码时不应在屏幕回显。确保 Ctrl-C 始终能中断程序。
子命令与健壮性
一致的子命令：对于复杂工具，建议采用 名词 动词 的层级结构，如 docker container create。保持子命令间的命名和行为一致。
响应性：程序必须响应迅速，即使在网络请求时也应立即给用户反馈。长时间任务应展示进度条。支持超时设置，且程序应能从中断处恢复执行（幂等性）。
兼容性：接口变更应有冗长的废弃提醒过程。不要支持自动缩写子命令，因为这会限制未来的扩展空间。
配置与分发
配置优先级：遵循 命令行标志 > 环境变量 > 项目配置文件（如 .env） > 用户全局配置 > 系统全局配置 的优先级顺序。配置文件建议遵循 XDG 规范存放于 ~/.config 目录。
环境变量：变量名仅限大写字母、数字和下划线。不要在环境变量中存储永久性秘密。
分发与分析：优先分发为单个二进制文件。提供简单的卸载方式。严禁在未经用户许可（Opt-in）的情况下收集使用情况或崩溃报告，必须尊重用户隐私并保持透明。