CLI 工具的审美：好用的命令行长什么样

rsync -av --delete src/ dst/ 这种命令，第一次看常常会让人停三秒：能用，但不亲近。

CLI 不是图形界面的低配版。它更像一种压缩过的交互：把按钮、表单、提示和状态都塞进一行字里。正因为压缩得很狠，体验只要差一点，就会被立刻放大。使用者未必会说“信息架构有问题”，但会直接说：不好用。

CLI 的审美不在“酷”，而在“收得住”。

好用的 CLI，先得让人敢下手

很多工具的问题，不是功能少，而是第一次运行就让人紧张。命令能执行，但不知道会改什么、删什么、覆盖什么。

所以，顺手的 CLI 第一件事不是展示能力，而是降低试错成本。

1. 默认行为要保守

“保守”不是功能弱，而是默认不做不可逆的事。删除、覆盖、批量写入、远程操作，都应该显式确认，或者至少提供预演模式。

预演模式就是先告诉你“将要发生什么”，但暂时不执行。

tool sync --dry-run

--dry-run 不是点缀，它常常决定一个工具能不能进入日常使用。

2. 帮助信息要像给人看，不是给作者自己看

很多 CLI 的 --help 输出像参数仓库：选项很多，但没有顺序，没有重点，也没有例子。

真正有用的帮助，至少要回答三件事：

• 这个工具是干什么的
• 最常见的两三种用法是什么
• 哪些参数危险，哪些参数常用

最差的帮助信息，是把所有参数平铺出来；稍好一点的，会按“常用 / 高级 / 调试”分组；再进一步，会直接给出能复制的示例命令。对大多数人来说，示例比定义更有用。

输出不是“打印日志”，而是在对话

CLI 的界面很小，输出就是全部体验。这里最常见的两个问题是：要么沉默，执行半天什么也不说；要么话太多，刷满屏幕但没有重点。

1. 该安静的时候安静

默认输出应该只保留结果、进度和警告。调试信息可以放到 --verbose。普通模式下，用户关心的是：成功没有，失败没有，下一步是什么。

如果每一步都打印内部细节，作者可能觉得“透明”，使用者只会觉得乱。

2. 错误信息要能指导下一步

“Error: invalid argument” 这种报错几乎等于没说。

更好的写法是三段式：

• 哪错了
• 为什么错
• 应该怎么改

比如：

错误：未找到配置文件
已查找：~/.config/tool/config.yaml
可执行：tool init 生成默认配置

这不只是“更友好”，而是减少反复查文档的次数。工具没有把上下文说清楚时，排错成本就会转移给使用者。好的 CLI 应该尽量让输出自解释，而不是逼着用户自己补全线索。

参数设计，决定了工具的脾气

CLI 的审美，很大一部分藏在参数命名里。

1. 名字要稳定，别炫技

同一个意思，不要同时出现三种写法；已经公开的参数，也不要轻易改名。对作者来说，改个参数只是重构；对使用者来说，可能是脚本失效、历史命令失效、肌肉记忆失效。

短参数和长参数也有分工。-f 适合高频操作，--force 适合可读性。两个都保留，通常比只留一个更合理。

2. 子命令要符合直觉

git commit、docker run、npm install 这类结构之所以耐用，不是因为它们先进，而是因为“工具名 + 动作”符合直觉。

反过来，如果一个工具把核心操作都藏在奇怪缩写里，或者把同一层级的功能拆得很散，用户就会频繁去查帮助。查一次没问题，次次查，通常就是结构没有设计好。

一些看起来小，其实很关键的细节

1. 退出码要可靠

退出码可以理解为“命令最后到底成功没成功”的机器信号。人眼看日志，脚本看退出码。

如果明明失败了却返回成功，或者有警告就直接返回失败，这种工具就很难接进自动化流程。CLI 一旦进入脚本、定时任务、部署链路，稳定比花哨重要得多。

2. 输出格式要能给人看，也能给机器读

同一份结果，最好既能默认展示得清楚，也能选择 JSON 这类结构化格式。

一个常见问题是：作者只做了“给人看”的表格，结果别人想接脚本时只能靠文本截取。短期能用，长期很脆弱。

3. 颜色、动画、符号都要克制

颜色不是不能用，但要有退路。日志写入文件、远程终端、窄屏窗口，这些场景都可能让漂亮输出变成噪音。能关闭颜色、能关闭动画、能在非交互环境自动降级，都属于成熟设计的一部分。

好工具往往有边界感

CLI 最容易失控的地方，是总想把自己做成平台。一个命令解决构建、部署、同步、清理、监控、告警，最后每个功能都能用，但都别扭。

命令行适合明确、离散、可组合的任务。它擅长“做一件事，然后把结果交给下一步”。如果一个工具开始承担太多状态管理、交互决策和长流程引导，图形界面、网页面板，甚至配置文件，往往更合适。

这里的审美不是“越简越好”，而是知道哪里该停。

一个简单的判断标准

判断一个 CLI 好不好，可以先看一个很实际的问题：三个月后重新打开终端，还记得怎么用吗？

记得住，通常说明命令名顺、参数少而稳、帮助信息够用、错误提示不绕。记不住，往往不是使用者记性差，而是工具把复杂度转嫁给了人。