别只做网页：vibe 项目的命令行工具（CLI）实战

你的 vibe 项目是个开发者工具：帮人批量处理文件、跑自动化工作流、调 AI 模型做任务。网页版做好了，很漂亮。然后你发现一个尴尬的现实：你的目标用户——开发者们——每天要重复做 20 次同样的操作，每次都要打开浏览器、点五下鼠标、等页面加载。他们心里想的是："这要是有个命令行，一行就搞定了。"

这篇指南的核心判断先摆出来：CLI 是开发者工具的母语。当你的用户是开发者、当操作高频重复、当任务需要进管道和自动化时，网页不是"更友好的界面"，而是多余的中间层。反过来，给普通消费者做个 CLI，那就是自杀——界面选错，产品就错了一半。下面是从"做不做"到"怎么做"的完整实战。

先划清边界：本文只管纯终端工具的命令设计、交互、分发与更新，走 npm/pip/brew/cargo 这些渠道。桌面应用的打包公证、应用商店审核不在本文范围内；浏览器扩展的上架也不在。终端，就只是终端。

一、做不做 CLI：三问决策

很多独立开发者做 CLI 的动机是错的："网页版做完了，顺手包个 CLI 吧，显得专业。"顺手做的 CLI，最后都死在没人维护。做 CLI 之前，先过三问——三问全"是"，才值得做；任一"否"，都是"别做"的信号。

问 1：用户是开发者（或重度终端用户）吗？CLI 的学习曲线是陡峭的，它假设用户不怕黑窗口、会看报错、懂管道。如果你的用户是运营、设计师、普通消费者，别做 CLI，你是在给他们制造痛苦。反过来，如果你的用户本来就住在终端里（程序员、运维、数据工程师），不给 CLI 才是制造痛苦。

问 2：操作高频重复吗？一个月用一次的配置向导，做成网页表单体验更好；一天用 20 次的构建、部署、批量处理，网页的每一次点击都是税。判断标准：如果用户会把你的操作写进脚本、设成定时任务、绑到快捷键上，那就是高频，CLI 是刚需。

问 3：任务适合进管道或自动化吗？这是 CLI 相对网页的决定性优势：输出可以被下一个命令消费（mycli list | jq ... | xargs ...），可以进 CI、进 cron、被 AI agent 调用。如果你的工具产出的是结构化数据、批量操作的结果，CLI 的价值会指数级放大。如果每次操作都是"看一眼结果、凭感觉点下一步"，那是人机协作场景，网页更合适。

两种明确的"别做"信号：一是你的核心交互是"浏览和发现"（比如逛模板市场、看数据看板）——终端不适合展示性、探索性的界面，硬做只会做出一个难用的半成品；二是你的用户需要"被引导"（新手教程、分步配置、富文本编辑）——这些在终端里做，成本是网页的数倍，效果还打折。

还有一个值得单独说的场景：AI agent 调用。2026 年的开发者工具，多了一个新用户：跑在终端里的 AI agent（Claude Code 这类）。它们调你的工具不靠点击，靠 shell。一个设计良好的 CLI（清晰的 --help、稳定的 --json 输出、规范的退出码），天然就是 agent 友好的。这不是让你为 AI 做 CLI，而是说：如果你已经决定做 CLI，顺手把"机器可读"做到位，会吃到 agent 生态的红利。这点在第三节细讲。

最后给一张"三选一"对照，帮你跟另外两种界面形态划清界：网页适合浏览、发现、被引导的新手流程；CLI适合开发者的高频重复操作和自动化；SDK/API适合把能力嵌进别人的程序里。三者不是互斥的——成熟的开发者工具往往是"网页管 onboarding、CLI 管日常、SDK 管集成"的组合。但一人团队的资源只够做好一个起点，起点就按三问来定，别贪。

二、命令行 UX：--help 就是你的文档首页

网页有 onboarding 流程、手册、tooltip；CLI 只有一个入口：--help。一个从没用过你工具的人，只靠 --help 能不能在 5 分钟内跑通第一个命令——这是检验 CLI UX 的唯一标准。

--help 的写法模板（每个命令都按这个来）：

$ mycli deploy --help
用法: mycli deploy [选项] <环境>

将当前项目部署到指定环境。

参数:
  <环境>              目标环境: staging 或 production（必填）

选项:
  --dry-run           只打印将要执行的步骤，不实际部署
  --json              以 JSON 格式输出结果（供脚本解析）
  -q, --quiet         静默模式：只输出错误和最终结果

示例:
  mycli deploy staging --dry-run    # 先演练一遍
  mycli deploy production           # 正式部署

退出码:
  0 成功  1 通用错误  2 参数错误  3 部署失败（已回滚）

注意几个细节：第一行"用法"给出最简形式；每个选项一句话说清；示例是必备的，没有示例的 --help 等于没写；退出码列表写出来，用户写脚本时才敢依赖你的退出码。

错误信息三要素：错在哪、为什么、怎么修。反例只有一行 Error: failed，用户只能去翻源码（如果他看得到源码的话）。正例：

# 反例
$ mycli deploy production
Error: failed

# 正例
$ mycli deploy production
错误: 无法连接到 API (https://api.example.com)
原因: 连接超时（10 秒），可能是网络问题或服务不可用
建议: 1) 检查网络连接  2) 用 mycli status 查看服务状态
      3) 如需帮助，带上 --debug 重跑并把输出贴到 issue

三要素缺一不可。"错在哪"定位问题，"为什么"给上下文，"怎么修"给行动。第三条里的 --debug 是个小技巧：给 CLI 加一个 debug 开关，输出请求 ID、耗时、原始报错，用户报 issue 时直接贴这段，你排查效率翻倍。

退出码规范：0 永远表示成功；1 通用错误；2 参数/用法错误（和 1 区分开，脚本作者会感谢你）；3 及以上按你的业务定义（部署失败、测试未通过等）。永远不要用退出码传业务数据（比如用退出码表示"找到了几个文件"）——退出码是给 shell 和 CI 看的信号，不是数据通道。

子命令的命名与结构也有讲究：用"动词 + 名词"的两级结构（mycli deploy production、mycli logs --tail 100），别超过三级——三级以上的命令树（mycli project env var set）说明你的概念模型太绕了，该重构。别名（alias）是低成本的高体贴：mycli d 等价于 mycli deploy，高频命令值得一个短别名。但别名要文档化，别搞"隐藏快捷键"。

三、交互与输出：参数 vs 交互式 prompt，人读 vs 机器读

CLI 有两种交互范式，选错了会同时得罪两类用户。

参数（flags/args）是默认范式。所有操作都应该能用一行命令完成，不依赖交互。这是 CLI 能进脚本、进 CI、被 agent 调用的前提。设计原则：必填参数越少越好——超过 3 个必填参数，就说明这个命令的职责太重了，该拆。善用合理的默认值和配置文件（第七节），让 80% 的场景一行命令搞定。

交互式 prompt 是补充范式，只用在两种场景：一是新手引导（第一次运行时的配置向导）；二是高风险操作前的确认（删除、覆盖、发 production）。其他场景用 prompt 都是错的——它会杀死脚本化能力。判断标准：任何 prompt 都必须有对应的 --yes/--force 参数可以跳过，CI 里没人给你按回车。

human / --json 双模式输出，这是 2026 年 CLI 的标配：

• 默认 human 模式：给人看的。可以有颜色、有表格、有 emoji、有进度条。排版可以任性，因为这是给眼睛看的。
• --json 模式：给机器看的。输出必须是合法的、结构稳定的 JSON，不要掺任何 human 格式的东西（进度条、彩色、"Done!"这种）。结构稳定意味着：字段只增不减，改名就是 breaking change。agent 和脚本依赖的是这个模式的稳定性。

一个常见错误是"半吊子 JSON"：加了 --json，但输出里混着日志行，jq 一解析就炸。铁律：--json 模式下，stdout 只能有 JSON，日志、进度、警告全部走 stderr。这条规则同时适用于 human 模式——进度条走 stderr，这样用户 mycli list > files.txt 重定向时，拿到的才是干净的数据。

进度反馈与静默模式：超过 2 秒的操作必须有进度反馈（进度条、spinner、阶段日志），否则用户会以为卡死了然后 Ctrl-C——而你的操作可能正进行到一半，留下脏状态。同时提供 --quiet：只输出错误和最终结果，给脚本和 CI 用。--quiet 和 --json 经常一起用，这是脚本作者最爱的组合。

大数据输出要分页：mycli list 返回上万行时，别一股脑全打出来。human 模式下接系统分页器（less），或默认只显示前 N 行并提示"共 X 条，用 --limit/--all 控制"；--json 模式下保持全量（机器不怕多），但提供 --limit 和游标参数。这个细节决定了你的 CLI 在数据量上来之后是"依然好用"还是"直接卡死"，而数据量上来是早晚的事。

四、技术选型：Node / Python / Go / Rust 怎么选

四条路线，没有银弹，只有权衡。一人团队选型的第一原则是：选你最熟的，别为"理论上最优"选一门你要现学的语言。CLI 的质量 90% 来自 UX 设计，10% 来自语言特性。

• Node（TypeScript）：生态最熟（你的网页大概率也是 JS 栈），和现有代码共享逻辑最方便。缺点是分发重：用户得装 Node，或你打成 pkg/nexe 单文件（体积大）。适合：已有 JS 后端、团队只会 JS 的情况。
• Python：AI/数据圈的默认语言，argparse/click/typer 写 CLI 极快。缺点同样是运行时依赖，用户环境 Python 版本千奇百怪。适合：AI 工具、数据处理类 CLI，用户本身就是 Python 用户。
• Go：一人团队做 CLI 的默认推荐。编译出单文件二进制，无运行时依赖，交叉编译极其省心（GOOS/GOARCH 一把梭），cobra 库的命令结构非常成熟。启动速度毫秒级。缺点是写起来比脚本语言啰嗦一点。适合：不知道选什么的时候选 Go，基本不会错。
• Rust：性能天花板，clap 的参数解析体验是四者里最好的，单文件分发同样优秀。缺点是开发速度慢、学习曲线陡。适合：对启动速度/内存极度敏感的工具（比如要塞进每个 shell prompt 里跑的），或者你本来就是 Rust 开发者。

决策简化成一句话：用户是 Python 生态的用 Python，有 JS 全栈用 Node，否则用 Go；Rust 留给性能偏执狂和 Rust 原住民。另外，无论选什么，第一天就把交叉编译的 CI 配好（至少 macOS arm64/amd64 + Linux amd64 + Windows amd64），别等到有人提 issue 说"Windows 上跑不起来"才手忙脚乱。

版本号策略顺带定一下：CLI 同样遵循 semver，但有一个 CLI 特有的 breaking change 要盯紧——输出格式的变化。--json 加字段是 minor，删字段、改名是 major；human 模式的表格列顺序变了，严格说也是 breaking（有人在用 awk 切你的输出，别笑，真有人这么干）。所以快照测试（第八节）不只是测试手段，更是你的"输出格式宪法"。

五、分发渠道：让用户用一条命令装上

CLI 的分发目标是：用户从"听说"到"跑起来"，不超过一条命令。每多一步，流失一半人。各渠道取舍：

• npm：前端/JS 用户的默认渠道。npm i -g mycli 或 npx mycli。即使你的 CLI 是 Go 写的，也可以用 npm 包做分发壳（postinstall 下载对应平台的二进制）——别惊讶，很多知名 CLI 都这么干，因为 npm 是覆盖率最高的"包管理器"。
• pip / pipx：Python 用户用 pipx（隔离环境装 CLI，比 pip 直接装干净）。Python 写的 CLI 必发。
• Homebrew：macOS 用户的信任背书。写个 Formula 放到自己的 tap 里，brew install yourname/tap/mycli。进官方 homebrew-core 门槛高（要有一定知名度），先从 tap 开始。
• cargo install：Rust 写的自然带上，Rust 用户习惯这个。
• GitHub Releases：所有渠道的"底座"。CI 打 tag 自动编译各平台二进制、上传到 Releases。这是 brew formula、npm postinstall 壳、curl 安装脚本共同的上游。先把 Releases 做好，其他渠道都是它的下游。

还要准备一条 curl 安装脚本（curl -fsSL https://.../install.sh | sh）：检测平台、下载对应二进制、放到 PATH 里。给它配上 checksum 校验——2026 年了，无校验的 curl|sh 等于把用户往火坑里推。另外，安装脚本只做最小的事：下载 + 放 PATH，别顺手改 shell 配置、别装依赖，越克制越可信。

六、自动更新：提醒，但不打扰

网页版更新是无感的，CLI 不是——用户的机器上躺着的是三个月前下载的二进制。自动更新的策略分三档，按需取用：

• 第一档：只提醒，不自动（首版推荐）。每次运行（或每天第一次运行）时检查一次新版本，有新版就在输出末尾加一行：📦 mycli v1.4.0 可用（当前 v1.3.2），运行 mycli upgrade 更新。检查要异步、要超时兜底（超过 2 秒就放弃，别让更新检查拖慢正常命令），并且尊重 --quiet（静默模式下不打印提醒）和无网络环境（失败就静默跳过）。
• 第二档：提供 upgrade 命令。mycli upgrade 自己下载新版替换自己。实现不复杂（下载到临时文件、校验、原子替换），但要处理好权限问题（装在系统目录下可能需要 sudo，这时要明确告诉用户，而不是静默失败）。
• 第三档：全自动更新。不推荐一人团队做——自动替换用户机器上的二进制是高风险操作，杀毒软件、签名校验、回滚，每一个都是坑。把选择权留给用户。

版本提示的文案也有讲究：只在有 minor 以上更新时提醒，patch 版本的 bugfix 不值得打扰用户。提醒文案里带上新版的一句话亮点（"v1.4 新增 --json 输出"），把"更新"从负担变成诱惑。

最后是回滚：mycli upgrade 替换二进制之前，先把旧版备份到 ~/.cache/mycli/previous，并提供 mycli rollback 一键回退。新版曾经出过回归 bug（一定会出的，别心存侥幸），用户在 issue 里骂的第一分钟，你能回一句"先跑 mycli rollback 回到上一版"，这就是专业支持和业余支持的区别。备份只保留最近一个版本，省空间，也避免"回滚到三年前"的玄学问题。

七、配置与密钥：XDG 是约定，钥匙串是底线

CLI 需要存两样东西：配置（API 地址、默认参数）和密钥（API key、token）。两者的存放规则完全不同，混在一起是新手最常见的错误。

配置文件：遵循 XDG Base Directory 规范——Linux/macOS 下放 ~/.config/mycli/config.yaml，别直接堆在 ~/ 根目录（用户的主目录不是你的垃圾场）。Windows 下用 %APPDATA%。配置文件支持多环境切换：mycli --profile prod / mycli --profile staging，或 MYCLI_PROFILE 环境变量。环境变量的优先级高于配置文件，命令行动参数高于环境变量——这个三层优先级是 CLI 世界的通用约定，别自创。

密钥：永远不要把密钥写进配置文件明文保存。两个正确选项：

• 系统钥匙串（推荐）：macOS Keychain、Windows Credential Manager、Linux Secret Service。用 mycli login 走一遍 OAuth 或输入 key，存进钥匙串。这是用户最信任的方式，也是安全审计眼里唯一及格的方式。
• 环境变量：MYCLI_API_KEY。适合 CI/服务器场景，用户自己负责保管。CLI 启动时读环境变量，读不到再去钥匙串找。

还要处理一个细节：--debug 输出和错误信息里，密钥必须脱敏（显示为 sk-...****）。用户会把 --debug 输出贴到公开的 issue 里，你不脱敏，等于帮他把 key 公开处刑。这个脱敏要在输出层统一做，别指望每个地方都记得。

八、测试：快照测试是 CLI 的单元测试

CLI 的测试和库不一样：用户看到的是文本输出，所以输出快照测试是核心。用工具（bats、pytest + subprocess、Go 的 testscript 都行）跑真实命令，把 stdout/stderr/退出码拍成快照，下次改代码时 diff 快照。任何输出格式的意外变化都会立刻现形——这对 --json 模式的结构稳定性尤其重要。

三层测试，按重要性排序：

• 快照测试：覆盖所有命令的 --help 输出、正常路径、每个错误分支。--help 进快照的好处是：你改文案时会 consciously（有意识地）看到 diff，而不是无意中改掉了用户依赖的文案。
• CI 多 OS 矩阵：至少 macOS + Linux + Windows。路径分隔符、换行符、权限模型，三个系统各有各的坑。Windows 是重灾区——别等用户报。
• 真实终端冒烟：发版前，在一台干净的机器（或容器）里走一遍安装 → login → 核心命令 → upgrade 全流程。这是拦住"在我机器上能跑"的最后一道网。

错误分支的测试经常被漏掉：专门写几个测试，模拟网络超时、401、配置文件损坏，看错误信息三要素是否还在、退出码对不对。CLI 的错误路径是用户最常看到的路径，值得同等的测试投入。

测试还有一条纪律：测试必须打在沙盒环境，别碰用户的真实数据。CLI 测试天然有破坏力（删文件、调 API、写配置），所以 mycli --profile test 这种隔离机制要在开发期就建好，测试全部跑在 test profile 里。冒烟测试也一样——用 staging 环境，不许拿 production 练手。这条写进 CONTRIBUTING，防的是未来的你手滑。

快照测试的维护成本常被高估：初期写 30 个快照用例大概半天，之后每次改动 diff 一眼就能看完。真正贵的是"没快照之后每次发版都心惊胆战"——那种焦虑感，经历过一次就知道半天投入有多值。

九、反模式：终端里的网页思维

• 把网页表单翻译成 20 个必填参数：网页上分三步填的表单，到 CLI 里变成一行 20 个 flag 的命令。这不是"移植"，是偷懒。正确做法是拆命令、给默认值、用配置文件承载常用值。
• 无 --help：--help 报错或只打印一句"详见文档"。等于告诉用户：想用我的工具，先去读网页。CLI 用户选择终端就是为了不离开终端。
• 错误信息只有 "Error"：前面讲过三要素，这里只强调后果——用户遇到这种错误，第一反应不是"我哪里用错了"，而是"这工具是半成品"，然后换竞品。
• 静默覆盖用户文件：没有任何确认就覆盖、删除用户文件。这是 CLI 世界里不可饶恕的罪——网页有回收站，终端的 rm 没有。高风险操作必须确认（可被 --yes 跳过），并且先备份。
• 输出混杂：--json 模式里混进日志行，human 模式的进度条打到 stdout。管道一接就炸，还查不出原因。stdout/stderr 分流是铁律。

十、首版 CLI 最小可用清单

发布前逐项打勾：

• ☐ 三问决策：用户是开发者、高频重复、可进管道，三问全"是"，不是"顺手做一个"；
• ☐ --help：每个命令都有完整 --help，含用法、选项、示例、退出码；新人 5 分钟能跑通第一个命令；
• ☐ 错误三要素：所有错误分支都有"错在哪/为什么/怎么修"，带 --debug 开关，密钥输出脱敏；
• ☐ 退出码：0 成功、1 通用错误、2 参数错误，业务码另行定义，不拿退出码传数据；
• ☐ 双模式：默认 human 可读，--json 输出纯净合法、字段稳定；日志与进度走 stderr；--quiet 可用；
• ☐ 交互克制：所有 prompt 都有 --yes/--force 可跳过；高风险操作先确认；
• ☐ 分发：GitHub Releases 自动出三平台二进制；至少一条命令能装上（npm/pipx/brew 任一）；安装脚本带 checksum；
• ☐ 更新：版本检查异步不阻塞，提醒文案带亮点，--quiet 下不打扰；
• ☐ 配置与密钥：XDG 规范路径，多 profile 切换，密钥进钥匙串或环境变量、不落明文；
• ☐ 测试：快照测试覆盖 --help 与错误分支，CI 跑三系统，干净环境冒烟通过。

最后回到开篇的判断：CLI 是开发者工具的母语。当你的用户住在终端里，网页是多余的中间层；反之，硬塞一个 CLI 给不需要它的人，同样是添堵。界面选对，事半功倍；选错，神仙难救。按这份清单做出第一个版本，然后去看你的用户怎么用——他们敲命令的方式，会告诉你下一步该做什么。