命令行界面设计指南
文章摘要
clig.dev 是一份开源的《命令行界面设计指南》（Command Line Interface Guidelines），由来自 Squarespace、Replicate 等公司的资深工程师撰写，把传统 UNIX 哲学与现代可用性实践结合起来，指导开发者写出更好用的 CLI 程序。它的基本立场是：现代 CLI 主要是给人用的，而不只是给其他程序用的，因此应当以用户体验为先，同时保持与其他工具的可组合性。
指南给出了七条核心哲学：以人为本、由简单可组合的部件构成（遵循 UNIX 传统，通过 stdin/stdout、退出码、纯文本互通）、跨程序保持一致（尊重用户的肌肉记忆和终端惯例）、恰当的信息密度（既不让人以为程序卡死，也不刷屏轰炸）、易于发现（借鉴 GUI，用完善的帮助、示例和纠错建议降低门槛）、对话式交互（承认 CLI 使用是反复试错的过程）、以及健壮与共情（让软件用起来稳、体现出你为用户考虑过）。
在此之上，指南给出了大量具体条款。基础层面：”成功返回 0、失败返回非零”，”正常输出走 stdout、消息走 stderr”，用成熟的参数解析库，一致地处理 -h/--help。帮助文档方面：默认输出精简用法，--help 给详细帮助，先给可运行示例，提供 man page，输入错误时建议相近命令。输出方面：优先人类可读，用 isatty 检测是否连接终端来决定格式，同时支持 --json 等机器可读格式；有意识地使用颜色并尊重 NO_COLOR；非终端时关闭动画。参数与标志：偏好显式标志而非位置参数，短/长标志并存，绝不用标志传递机密，用 - 表示 stdin/stdout。此外还涵盖交互（仅当 stdin 为 TTY 时才提示、支持 --no-input、密码不回显、Ctrl-C 要灵敏）、子命令、健壮性（100ms 内给反馈、长任务显示进度、网络操作设超时）、面向未来（改动保持向后兼容）、配置优先级（命令标志 > 环境变量 > 项目配置 > 用户配置 > 系统配置）、命名、分发（尽量单二进制文件）和分析（未经明确同意绝不收集使用数据）。核心要点是：优秀的 CLI 要在”与程序协作”和”讨人类喜欢”、”遵循惯例”和”保持创新”之间取得平衡。
HN 评论精华
- 关于”程序运行几分钟没输出会让人以为坏了就该报进度”这一条，kazinator 强烈反对：如果程序规范就是安静地算完再输出（比如
cp -r），那即使算三周也不该输出杂音。他设想应有一个约定的进度上报协议（比如专门的 fd 3 作为 “stdprogress”），但绝不能默认混在正常输出里。 - 由此引出对 stderr 的讨论。matheusmoreira 认为正确做法就是”输出走 stdout、面向用户的消息走 stderr”，并调侃 fd 2 当初该叫”user 流”而不是”error 流”。多位评论者补充了 BSD 的 SIGINFO、
OSC 9;4终端进度条、以及 PowerShell 的七种输出流等替代方案。 - 最激烈的争论集中在自动分页（pager） 上。指南建议”输出很多文本时用 less 分页”，eikenberry、keithnz、inetknght 等人极力反对，认为这违背了”模块化、可自由组合”的核心原则——”我想分页自己会管道给 pager，退出 pager 后我还想在屏幕上看到输出”。ventana 则解释这正是
git log用isatty的做法，并给出用PAGER=cat、LESS=-XF、git config core.pager cat等多种关闭方法；yjftsjthsd-h 补充说systemctl status那种”时而分页、时而不分页”的行为尤其令人抓狂。 - atiedebee 与 oneeyedpigeon 批评近年的趋势是”裸命令输出一大堆、
--help输出更多还不分页、却没有 man page”，主张：每个程序都该有 man page，裸命令给单行用法，--help给不超过一屏的概览。chriswarbo 赞赏 Nix 命令的做法——--help直接调man打开对应手册页。 - jodrellblank 尖锐吐槽了”程序明明知道你用错了、也能直接打印帮助，却偏偏训你一顿让你自己去敲
--help“的糟糕体验，把这种”翘着二郎腿的 C3PO 式仆人”行为比作大家讨厌的 LLM 腔调。