终端的魅力就在于你讨厌反复做的事总有一条命令能替你干完。我最早被“命令行”这个东西打动不是因为它看起来很酷而是因为一个很朴素的场景每天要打开十几个不同的网页、填不同的表单、复制不同接口的参数才能完成一次数据收集。那时候我就在想如果能把这一切收敛成一行命令在终端里敲下去接下来所有的脏活累活全部自动完成那该多省心。后来我真的把这套想法做成了一个叫CLI-Anything的开源小项目核心理念就一句话把任意场景、任意操作、任意服务统统封装成你顺手的命令行工具。1. CLI-Anything 到底是什么想解决什么问题1.1 一次“多余操作”引发的思考很多写代码的朋友都遇到过这类情况某个内部平台只有网页版你每天要从里面导数据某个接口要带一堆签名参数你用 Postman 点半天才能调通某个文件要按固定规则改名、压缩、归档你每周手动处理一次。这些事情本质上都是“重复操作”但它们分散在各个工具和网页里没有一个统一的入口。而CLI 恰恰是最适合做统一入口的地方——终端是天然的“自动化控制台”它不仅能执行命令还能组合命令、承接管道、挂进定时任务。我最初做 CLI-Anything 的动机就是想把这些零散的“重复操作”从网页、图形界面、脚本文件里抽出来变成一个接一个、可以随时调用、也可以互相组合的命令。它不是一个只能跑一个场景的专用脚本而是一个“能造命令的命令行工具”——你只管定义“这个命令要做什么”剩下的参数解析、输出美化、错误处理、配置文件读取它帮你包掉。1.2 典型场景与现实收益举个例子会更直观。假设你是一个后端工程师每天上线前都要检查三个环境的健康状态。原来你需要依次打开监控页面、登录服务器、敲一串 curl 命令、把结果贴到群里。用 CLI-Anything 你可以定义一个health-check命令敲一下它会并发请求这三个环境判断状态码和响应时间把结果打印成一张清晰的表格。如果某一个环境挂了它还会直接标红并返回非零退出码——这样你连 CI 流水线都可以挂上它做自动判活。这类场景我总结了一下通常有四个特征动作重复固定周期、固定步骤比如每天、每周都要做。需要判断结果不是简单的一行文字而要经过加工、汇总、判断状态。分散在多处要在网页、服务器、第三方 API 之间来回切换。一旦出错代价高漏看某个指标可能到线上才发现问题。CLI-Anything 解决的就是这一类事情。它把分散在各处的操作收敛成一个统一命令让终端成为你所有自动化任务的入口。对前端、后端、运维、数据分析师来说它都能省下不少来回折腾的时间。1.3 与传统脚本和现成框架的关系有人可能会问我自己写个 Node 脚本、Python 脚本也能做到为什么要用 CLI-Anything 这种封装层我的回答是你当然可以写但大部分手写脚本都有同样的问题——参数解析要自己处理帮助文档要自己拼输出格式要自己调颜色异常情况要自己处理。你重复写了十次之后就会发现自己其实是在重复造同一个轮子。CLI-Anything 把“命令行工具开发的公共部分”全部抽出来了你只需要关注“你的业务逻辑”。它和手写脚本并不是对立的而是一个上下游关系手写脚本解决的是“具体任务怎么做”它解决的是“这个任务怎么变成一条完整的命令”。至于生态里的 commander、yargs、click 这些成熟框架我也用过不少CLI-Anything 的差异点是它更轻并且默认把“命令定义”和“业务逻辑”解耦——你甚至可以不用写一行代码只靠一个 JSON/YAML 描述文件就能生成一个可用的命令。这是它特别适合“非专业工具开发者”的原因。2. 命令系统的核心骨架2.1 命令与参数解析CLI 的“门面”一条成熟的 CLI 命令看起来很简单比如weather -c beijing --format json但背后要做的事情其实不少。首先你要区分“位置参数”和“选项参数”beijing是位置参数-c是短选项--format是长选项它们的解析规则不一样。我见过很多手写脚本在这里翻车比如参数之间因为空格被拆开、-cbeijing这种粘连写法没处理好、--format json和--formatjson两种写法结果不一致等等。CLI-Anything 在设计参数解析时遵循了几条我觉得很重要的原则位置参数尽量做到不超过三个超过三个用选项参数承载。短选项和长选项必须同时支持并且允许用户混写。所有参数都要有默认值不能让用户为了“填一个永远不变的参数”而感到烦躁。布尔型选项支持--no-前缀反转比如--color和--no-color。这些设计不是拍脑袋定的。比如布尔反转在我做过的工具里就很有用——很多人希望“默认彩色遇到特殊场景再关闭”如果没有--no-color就得让用户去改配置文件体验一下子就差了很多。CLI 的第一体验就是“敲命令、看反馈”如果第一层参数解析就让你难受后面的功能再强大也留不住用户。2.2 子命令分发从“一条命令”到“一个工具箱”单个命令只能解决单点问题真正让 CLI 好用起来的是“命令簇”。git push、git commit、git merge本质上就是一个“大工具下有多个子命令”的结构。CLI-Anything 也采用了类似的体系一个项目可以注册多个子命令每个子命令拥有独立的名称、参数、执行逻辑和帮助说明。在具体实现上分发逻辑其实不复杂把用户输入的process.argv切掉前两段之后第一个非选项的字符串就是子命令名剩余的部分全部交给该命令的解析器处理。难点在于“分发时如何处理公共参数”比如所有子命令都要支持的--debug、--config、--quiet。我选择的处理方式是在顶层先做一次“参数预检”把公共选项剥离出来再下发给子命令。这样做的好处是每个子命令的实现不需要重复关心这些公共逻辑。提示不要在设计命令树的时候嵌入太深的层级。二级子命令已经足够覆盖绝大多数场景三级以上会让“命令可记忆性”大幅下降。我试过在项目里做一个三级子命令backup remote create结果我自己过两天都记不住果断砍掉了。2.3 帮助文档被严重低估的“门面”很多脚本开发者不重视帮助文档觉得“只要功能能用就行”。但 CLI 是一个没有图形界面的工具用户上手的第一件事就是敲--help。帮助文档写得清不清楚直接决定你这个工具是让人爱不释手还是让人望而却步。CLI-Anything 会自动从命令定义里生成帮助文档包括用法说明、参数列表、示例片段不需要手写。我个人在帮助文档上的经验是光列出参数名称远远不够每个参数都要写上“默认值”和一个“真实示例”。比如weather -c beijing --format table --days 3这比干巴巴地写“-c, --city 城市名”要直观得多。用户在帮助文档里看到一次真实示例大概就明白这个命令怎么用了。我会要求项目里每条命令的帮助文档至少包含两个示例一个是最简用法一个是完整用法。这件事虽然琐碎但收益非常明显——我同事第一次用我的工具基本都不用来问我自己敲个--help就知道怎么操作了。3. “Anything”插件化与命令定义3.1 用配置文件定义一个命令“Anything”这个后缀代表的不是“什么都能做”的夸张而是一种设计思想命令不应该依赖特定业务场景而应该可以描述任意业务场景。为了让这个想法落地我设计了“命令描述文件”的机制。你不需要写代码只需要写一份 JSON 或者 YAML声明这个命令叫什么、带什么参数、要执行什么操作CLI-Anything 就会把它变成一条真实可执行的命令行工具。一个最简单的命令描述文件看起来像这样name: hello description: 演示命令输出问候语 args: - name: user required: true description: 你的名字 action: type: shell command: echo hello {{user}}这个文件本身很好理解定义了一个hello命令有一个必填参数user执行时会把它替换进一个 shell 命令里。可能有人会觉得这太简单了但我想说的是描述文件的价值在于“把命令变成可交换、可管理、可版本化的数据”。你在项目里维护一个commands/目录里面放着所有命令的描述文件新同事一进项目就能看懂有哪些命令、每个命令做什么。如果某天你想给某个命令加参数改一行配置就好不用去翻代码。3.2 插件加载机制让“不写代码”和“写代码”并存配置文件能覆盖一部分场景但真正复杂的业务逻辑比如调用某个内部 SDK、操作数据库、解析文件内容靠配置文件里的 shell 命令是不现实的。所以 CLI-Anything 还提供了一套插件机制命令描述文件里可以声明action.type: plugin然后指定一个插件文件名。这个插件就是一个普通的 Node.js 函数接收解析好的参数和上下文对象返回结果数据。这个设计解决了一个很实际的问题不同团队的开发者可以按自己熟悉的方式为同一个 CLI 体系贡献命令。不擅长写代码的人可以用配置文件定义简单的命令熟悉 Node.js 的人可以写插件处理复杂逻辑。而且插件和配置文件可以同时在一条命令里出现——先由配置声明参数再由插件处理数据。插件机制的实现也很有意思核心就是一个“命令注册表”启动时扫描目录读取描述文件把插件文件按名称关联起来。整个加起来不过几十行代码但带来的扩展性是巨大的。你可以把插件想象成“乐高块”CLI-Anything 是底板每块插件都是一块标准尺寸的积木怎么拼、拼成什么完全由你决定。3.3 命令输出的规范化很多人做 CLI 工具输出格式非常随意。有时候 console.log 一个嵌套很深的对象有时候自己拼字符串。这种随意的输出在“给人看”的时候问题不大但一旦想把命令接进别的程序、写进日志、挂进 CI就非常痛苦。CLI-Anything 对输出做了三层设计默认输出是“人友好”的彩色表格或缩进文本。通过--format json可以切换到 JSON 输出便于程序消费。通过--output参数可以把结果写进文件而不是打印到屏幕。这三层看起来简单却是“命令能否被复用”的关键。我之前写过不少一次性脚本最大的教训就是第一次写命令只考虑了“人看”结果第二次想在别的地方复用才发现解析文本有多痛苦。所以现在凡是项目里的命令我都要保证“核心数据是结构化的”——哪怕默认输出是格式化好的表格内部的数据流也必须是 JSON 对象。这个原则让 CLI-Anything 的命令很容易被其他命令调用也很容易被测试。4. 交互体验让你的命令用起来顺手4.1 彩色输出与终端心智CLI 工具为什么好用的一个关键点是“反馈清晰”。当你敲下一条命令终端滚动输出几十行文字如果没有颜色区分用户必须逐行去读才能找到哪是重点。彩色输出并不是为了好看而是为了“引导视觉”。CLI-Anything 内置了一套基于 chalk 的颜色规范错误用红色、警告用黄色、成功用绿色、流程标题用蓝色辅助信息用灰色。这套规范看似简单但我在实际使用中确实能明显加快信息读取速度。举个我自己的例子一个deploy命令执行过程中会打印步骤名称、编译日志、服务器响应。如果没有颜色所有内容混在一起你要花心思去分辨“哪一步成功、哪一步失败”有了颜色之后一眼扫过来绿色就是成功了、红色就是出错了非常直观。但这里要注意一个细节在有颜色环境里舒适使用不代表在所有环境里都舒适。管道、CI 和编辑器的终端很多不支持 ANSI 颜色所以 CLI-Anything 默认在非 TTY 环境下会自动关闭颜色这个逻辑也可以通过--no-color手动控制。4.2 进度反馈与交互确认命令执行时间有长有短短命令无所谓但长命令没有进度反馈用户会怀疑“是不是卡死了”。CLI-Anything 的插件 API 里提供了一个progress对象算是对批量任务场景的支持。比如要批量上传 100 个文件你可以每上传一个就更新一次进度终端上会显示“12/100 已完成”。这个功能的实现不复杂本质就是利用终端的回车键和覆盖写入但效果非常显著。交互确认则解决的是“危险操作”的问题。比如clean-cache命令会删除本地缓存目录这种操作如果一声不吭地执行用户可能忘记自己曾经敲过这个命令反应过来已经删完了。CLI-Anything 允许在命令描述里声明confirm: 真的要清理全部缓存吗执行时就会先询问用户得到肯定答复后才继续。这个设计在面向生产力场景时必须要有因为命令行的好处是快坏处也是快——快到你来不及后悔。4.3 错误处理与退出码约定关于错误处理我认为“退出码”是 CLI 里最应该规范、却又最容易被忽略的东西。很多手写脚本无论成功失败都是exit(0)这对交互式使用影响不大但一旦挂到 CI 流水线或 shell 脚本里判断“命令是否成功”靠的就是退出码一个错误的 0 会让后面一连串步骤错误地继续往下走。CLI-Anything 里我强制每条命令返回一个退出码0 表示成功1 表示业务错误2 表示参数解析错误。业务错误和参数错误区别对待这样自动化脚本才能采取不同的处理策略。同时错误信息本身也要有结构。不能说一条命令报错就只是控制台打印一行红色文字而要在结构化输出里包含错误码、错误消息、可能的原因和操作建议。CLI 工具做得不好的典型表现是“给你一个孤零零的错误码让你自己去查文档”好的工具应该像朋友一样直接告诉你下一步该怎么办。5. 从零开始的完整实操把一个 API 封装成命令5.1 初始化项目这部分我直接带你走一遍完整流程目标是把和风天气的城市查询接口封装成一条weather命令。选这个例子是因为它足够典型有外部 HTTP 请求、有参数输入、有结构化输出、还有错误处理几乎覆盖了大部分 CLI 场景。首先初始化项目mkdir cli-weather-demo cd cli-weather-demo npm init -y npm install cli-anything安装完成后在项目根目录创建一个commands/目录CLI-Anything 默认会从这个目录加载命令描述文件。5.2 定义命令描述文件新建commands/weather.yaml内容如下name: weather description: 查询指定城市的当前天气 args: - name: city required: true description: 城市拼音或城市 ID例如 beijing - name: days description: 未来几天的预报 default: 1 - name: format description: 输出格式table 或 json default: table action: type: plugin plugin: weather.js这个文件解决的是“命令怎么被调用”的问题包括参数名称、是否必填、默认值。真正干活的逻辑交给插件weather.js。5.3 编写插件逻辑创建commands/weather.js内容是标准的 Node.js 模块const axios require(axios); async function run(ctx) { const { city, days, format } ctx.args; const apiKey ctx.env.WEATHER_API_KEY; if (!apiKey) { throw new Error(缺少 WEATHER_API_KEY 环境变量请先设置); } const url https://api.example.com/v7/weather; const { data } await axios.get(url, { params: { key: apiKey, location: city, days: days } }); const now data.now; const rows [{ 城市: city, 温度: ${now.temp}°C, 天气: now.text, 湿度: ${now.humidity}%, 风速: ${now.windSpeed} km/h }]; ctx.render(rows, { format }); return 0; } module.exports { run };这里的关键点有几个。第一插件接收一个上下文对象ctx里面已经包含了解析好的参数和所有环境变量你不需要自己去解析process.argv。第二错误处理用throw抛出CLI-Anything 会自动捕获并处理用户会看到红色错误信息退出码为 1。第三输出用ctx.render它负责把结构化数据渲染成表格或者 JSON不需要你手动拼字符串。5.4 打包与发布为全局命令在本地能跑通之后把它变成全局命令只需要两步。先在package.json里声明 bin 字段{ bin: { cli-anything: ./bin/cli-anything.js } }然后运行npm link就可以在任意目录下使用weather -c beijing --days 3 --format json这个过程之所以简单是因为 CLI-Anything 本身已经处理好了全局安装时的命令入口、参数解析、帮助文档生成等所有问题。你只需要维护一个 commands 目录每个命令就是一个 YAML 加一个 JS。拿到任何新的项目我通常都会先搭一个这样的骨架后续加命令完全是“复制粘贴再改改”的程度。5.5 让命令可组合最后再提一个 CLI 的进阶玩法命令组合。CLI-Anything 的输出默认支持结构化数据这让你可以把一条命令的结果接进另一条命令的操作里。比如我定义了一个scan命令能列出所有待发布的服务又定义了一个deploy命令可以发布指定服务那我在终端里可以这样写scan --format json | jq .services[] | .name | xargs -I {} cli deploy {}这一行命令做的事相当于“看清有哪些服务、然后挨个发布它们”。这种能力是 GUI 操作很难提供的——在图形界面里你必须一步一步点在 CLI 世界里你可以把命令当乐高积木拼出你想要的行为。而这一切的前提就是输出结构化和标准化的退出码CLI-Anything 在这两条路上已经帮你铺好了地基。6. 常见问题与排查技巧实录6.1 参数解析的边界情况参数解析看起来简单实际用的人多了各种奇怪的输入都会出现。我自己踩过不少坑挑几个典型的说。第一个是“负号开头的值”比如temperature -5解析器很容易把-5当成一个未知选项。解决办法是在定义参数时显式声明allowNegative: true或者强制用户加--分隔符temperature -- -5。第二个是“值中间有空格”比如查询一个带空格的城市名New York如果用户在命令行里不加引号就会被拆成两个参数。第三个是“布尔参数的--no-前缀”这个前面提过但值得再强调一遍如果你提供了一个默认开启的开关一定同时提供关闭它的方式。这些边界情况在图形界面上根本不存在但在 CLI 里很常见。我的建议是在项目早期就把所有参数解析的边界情况列成一个测试清单用自动化测试锁住行为。不然等项目大了你改一行解析逻辑可能会影响到所有命令。6.2 管道与 CI 环境下的输出差异很多命令在终端里运行得很好一接进管道或者 CI 就出问题。最常见的两类一类是颜色代码污染问题本来好看的红绿字在日志文件里变成了一堆[31m这样的转义序列一类是输出到文件时仍然走了表格格式而不是 JSON导致后续程序很难解析。CLI-Anything 给出的方案是默认检测process.stdout.isTTY非 TTY 环境下自动关闭颜色、默认输出 JSON。但这个自动检测也有失灵的时候所以更可靠的做法是显式传--format json --no-color给命令。注意在 CI 流水线里如果遇到输出格式问题第一件事不要改代码逻辑先加上--format json --no-color试一次。多数时候问题只在“输出层”和业务逻辑无关。6.3 跨平台兼容的三个大坑命令行工具最容易忽略的就是跨平台问题。我自己主要开发环境是 macOS但用户里用 Windows 的不少一发布出去就各种报问题。常见的三个坑路径分隔符Windows 用\POSIX 用/拼接路径时要用path.join不要手写字符串。换行符Windows 默认\r\n如果你在命令里用正则匹配文本很容易因为\r匹配不上。环境变量Windows 下通过%VAR%引用POSIX 下是$VARCLI-Anything 插件 API 里统一提供了ctx.env对象就是为了避免你直接操作 shell。解决这些问题没有捷径就是要在设计 API 时就藏好这些系统差异业务代码里不要直接碰系统调用。6.4 命令命名冲突CLI 工具发布出去你精心起的命令名可能已经和系统自带命令、其他工具的命令撞车了。比如我早期做一个工具想让用户用host这个命令调用结果发现host在 Unix 系统里已经存在了而且功能完全不一样。这会让用户非常困惑。我的建议是给命令名加一个独特的前缀比如cla-或者cx-。虽然三个字母的短命令看起来很酷但在真实生产环境里避免命令名冲突比酷更重要。如果确实要用一个短名字可以考虑在安装时询问用户是否需要创建别名而不是默认覆盖。说白了命名是一个工程问题不是审美问题。一个不能稳定依赖的命令名再短再酷也没有用。6.5 常见问题速查表现象可能原因排查/解决办法-5被当成未知选项参数解析器不认识负数显式声明allowNegative: true或用--分隔输出里出现[31m颜色码非 TTY 环境未自动关闭颜色显式加--no-color参数Windows 下路径拼接错误手写字符串拼接分隔符改用path.join不要手动加斜杠CI 里命令报错但退出码为 0脚本未正确传播错误检查插件是否返回非零退出码--help里有中文字段乱码终端编码不是 UTF-8Windows 下执行chcp 65001切换 UTF-8插件找不到模块NODE_PATH设置不正确用绝对路径或打包场景优先选择 ncc/webpack 等方案命令名和系统命令冲突全局命令重名增加前缀或安装时提示别名结尾一句大实话如果你问我做 CLI-Anything 最大的收获是什么我的回答不是代码本身而是“把工具做顺手”带来的长期回报。命令行工具最大的特点就是“复利效应”——每一次把它打磨好后续的每一天你都会重复使用它省下的时间会像滚雪球一样越滚越大。我个人现在的习惯是凡是需要做第二次的重复操作一定会停下来想能不能把它做成一个命令如果能就立刻动手。这种习惯可能不会让你一天省下很多时间但一年下来真的很可观。另外分享一个实用一点的小技巧你做的第一个命令永远不要试图覆盖太复杂的场景从一个输入参数、一个输出结果的小功能开始就好。等这个命令真正用顺手了你自然会知道它哪里该加参数、哪里该拆子命令到时候再迭代方向感会清晰得多。
终端的魅力就在于你讨厌反复做的事总有一条命令能替你干完。我最早被“命令行”这个东西打动不是因为它看起来很酷而是因为一个很朴素的场景每天要打开十几个不同的网页、填不同的表单、复制不同接口的参数才能完成一次数据收集。那时候我就在想如果能把这一切收敛成一行命令在终端里敲下去接下来所有的脏活累活全部自动完成那该多省心。后来我真的把这套想法做成了一个叫CLI-Anything的开源小项目核心理念就一句话把任意场景、任意操作、任意服务统统封装成你顺手的命令行工具。1. CLI-Anything 到底是什么想解决什么问题1.1 一次“多余操作”引发的思考很多写代码的朋友都遇到过这类情况某个内部平台只有网页版你每天要从里面导数据某个接口要带一堆签名参数你用 Postman 点半天才能调通某个文件要按固定规则改名、压缩、归档你每周手动处理一次。这些事情本质上都是“重复操作”但它们分散在各个工具和网页里没有一个统一的入口。而CLI 恰恰是最适合做统一入口的地方——终端是天然的“自动化控制台”它不仅能执行命令还能组合命令、承接管道、挂进定时任务。我最初做 CLI-Anything 的动机就是想把这些零散的“重复操作”从网页、图形界面、脚本文件里抽出来变成一个接一个、可以随时调用、也可以互相组合的命令。它不是一个只能跑一个场景的专用脚本而是一个“能造命令的命令行工具”——你只管定义“这个命令要做什么”剩下的参数解析、输出美化、错误处理、配置文件读取它帮你包掉。1.2 典型场景与现实收益举个例子会更直观。假设你是一个后端工程师每天上线前都要检查三个环境的健康状态。原来你需要依次打开监控页面、登录服务器、敲一串 curl 命令、把结果贴到群里。用 CLI-Anything 你可以定义一个health-check命令敲一下它会并发请求这三个环境判断状态码和响应时间把结果打印成一张清晰的表格。如果某一个环境挂了它还会直接标红并返回非零退出码——这样你连 CI 流水线都可以挂上它做自动判活。这类场景我总结了一下通常有四个特征动作重复固定周期、固定步骤比如每天、每周都要做。需要判断结果不是简单的一行文字而要经过加工、汇总、判断状态。分散在多处要在网页、服务器、第三方 API 之间来回切换。一旦出错代价高漏看某个指标可能到线上才发现问题。CLI-Anything 解决的就是这一类事情。它把分散在各处的操作收敛成一个统一命令让终端成为你所有自动化任务的入口。对前端、后端、运维、数据分析师来说它都能省下不少来回折腾的时间。1.3 与传统脚本和现成框架的关系有人可能会问我自己写个 Node 脚本、Python 脚本也能做到为什么要用 CLI-Anything 这种封装层我的回答是你当然可以写但大部分手写脚本都有同样的问题——参数解析要自己处理帮助文档要自己拼输出格式要自己调颜色异常情况要自己处理。你重复写了十次之后就会发现自己其实是在重复造同一个轮子。CLI-Anything 把“命令行工具开发的公共部分”全部抽出来了你只需要关注“你的业务逻辑”。它和手写脚本并不是对立的而是一个上下游关系手写脚本解决的是“具体任务怎么做”它解决的是“这个任务怎么变成一条完整的命令”。至于生态里的 commander、yargs、click 这些成熟框架我也用过不少CLI-Anything 的差异点是它更轻并且默认把“命令定义”和“业务逻辑”解耦——你甚至可以不用写一行代码只靠一个 JSON/YAML 描述文件就能生成一个可用的命令。这是它特别适合“非专业工具开发者”的原因。2. 命令系统的核心骨架2.1 命令与参数解析CLI 的“门面”一条成熟的 CLI 命令看起来很简单比如weather -c beijing --format json但背后要做的事情其实不少。首先你要区分“位置参数”和“选项参数”beijing是位置参数-c是短选项--format是长选项它们的解析规则不一样。我见过很多手写脚本在这里翻车比如参数之间因为空格被拆开、-cbeijing这种粘连写法没处理好、--format json和--formatjson两种写法结果不一致等等。CLI-Anything 在设计参数解析时遵循了几条我觉得很重要的原则位置参数尽量做到不超过三个超过三个用选项参数承载。短选项和长选项必须同时支持并且允许用户混写。所有参数都要有默认值不能让用户为了“填一个永远不变的参数”而感到烦躁。布尔型选项支持--no-前缀反转比如--color和--no-color。这些设计不是拍脑袋定的。比如布尔反转在我做过的工具里就很有用——很多人希望“默认彩色遇到特殊场景再关闭”如果没有--no-color就得让用户去改配置文件体验一下子就差了很多。CLI 的第一体验就是“敲命令、看反馈”如果第一层参数解析就让你难受后面的功能再强大也留不住用户。2.2 子命令分发从“一条命令”到“一个工具箱”单个命令只能解决单点问题真正让 CLI 好用起来的是“命令簇”。git push、git commit、git merge本质上就是一个“大工具下有多个子命令”的结构。CLI-Anything 也采用了类似的体系一个项目可以注册多个子命令每个子命令拥有独立的名称、参数、执行逻辑和帮助说明。在具体实现上分发逻辑其实不复杂把用户输入的process.argv切掉前两段之后第一个非选项的字符串就是子命令名剩余的部分全部交给该命令的解析器处理。难点在于“分发时如何处理公共参数”比如所有子命令都要支持的--debug、--config、--quiet。我选择的处理方式是在顶层先做一次“参数预检”把公共选项剥离出来再下发给子命令。这样做的好处是每个子命令的实现不需要重复关心这些公共逻辑。提示不要在设计命令树的时候嵌入太深的层级。二级子命令已经足够覆盖绝大多数场景三级以上会让“命令可记忆性”大幅下降。我试过在项目里做一个三级子命令backup remote create结果我自己过两天都记不住果断砍掉了。2.3 帮助文档被严重低估的“门面”很多脚本开发者不重视帮助文档觉得“只要功能能用就行”。但 CLI 是一个没有图形界面的工具用户上手的第一件事就是敲--help。帮助文档写得清不清楚直接决定你这个工具是让人爱不释手还是让人望而却步。CLI-Anything 会自动从命令定义里生成帮助文档包括用法说明、参数列表、示例片段不需要手写。我个人在帮助文档上的经验是光列出参数名称远远不够每个参数都要写上“默认值”和一个“真实示例”。比如weather -c beijing --format table --days 3这比干巴巴地写“-c, --city 城市名”要直观得多。用户在帮助文档里看到一次真实示例大概就明白这个命令怎么用了。我会要求项目里每条命令的帮助文档至少包含两个示例一个是最简用法一个是完整用法。这件事虽然琐碎但收益非常明显——我同事第一次用我的工具基本都不用来问我自己敲个--help就知道怎么操作了。3. “Anything”插件化与命令定义3.1 用配置文件定义一个命令“Anything”这个后缀代表的不是“什么都能做”的夸张而是一种设计思想命令不应该依赖特定业务场景而应该可以描述任意业务场景。为了让这个想法落地我设计了“命令描述文件”的机制。你不需要写代码只需要写一份 JSON 或者 YAML声明这个命令叫什么、带什么参数、要执行什么操作CLI-Anything 就会把它变成一条真实可执行的命令行工具。一个最简单的命令描述文件看起来像这样name: hello description: 演示命令输出问候语 args: - name: user required: true description: 你的名字 action: type: shell command: echo hello {{user}}这个文件本身很好理解定义了一个hello命令有一个必填参数user执行时会把它替换进一个 shell 命令里。可能有人会觉得这太简单了但我想说的是描述文件的价值在于“把命令变成可交换、可管理、可版本化的数据”。你在项目里维护一个commands/目录里面放着所有命令的描述文件新同事一进项目就能看懂有哪些命令、每个命令做什么。如果某天你想给某个命令加参数改一行配置就好不用去翻代码。3.2 插件加载机制让“不写代码”和“写代码”并存配置文件能覆盖一部分场景但真正复杂的业务逻辑比如调用某个内部 SDK、操作数据库、解析文件内容靠配置文件里的 shell 命令是不现实的。所以 CLI-Anything 还提供了一套插件机制命令描述文件里可以声明action.type: plugin然后指定一个插件文件名。这个插件就是一个普通的 Node.js 函数接收解析好的参数和上下文对象返回结果数据。这个设计解决了一个很实际的问题不同团队的开发者可以按自己熟悉的方式为同一个 CLI 体系贡献命令。不擅长写代码的人可以用配置文件定义简单的命令熟悉 Node.js 的人可以写插件处理复杂逻辑。而且插件和配置文件可以同时在一条命令里出现——先由配置声明参数再由插件处理数据。插件机制的实现也很有意思核心就是一个“命令注册表”启动时扫描目录读取描述文件把插件文件按名称关联起来。整个加起来不过几十行代码但带来的扩展性是巨大的。你可以把插件想象成“乐高块”CLI-Anything 是底板每块插件都是一块标准尺寸的积木怎么拼、拼成什么完全由你决定。3.3 命令输出的规范化很多人做 CLI 工具输出格式非常随意。有时候 console.log 一个嵌套很深的对象有时候自己拼字符串。这种随意的输出在“给人看”的时候问题不大但一旦想把命令接进别的程序、写进日志、挂进 CI就非常痛苦。CLI-Anything 对输出做了三层设计默认输出是“人友好”的彩色表格或缩进文本。通过--format json可以切换到 JSON 输出便于程序消费。通过--output参数可以把结果写进文件而不是打印到屏幕。这三层看起来简单却是“命令能否被复用”的关键。我之前写过不少一次性脚本最大的教训就是第一次写命令只考虑了“人看”结果第二次想在别的地方复用才发现解析文本有多痛苦。所以现在凡是项目里的命令我都要保证“核心数据是结构化的”——哪怕默认输出是格式化好的表格内部的数据流也必须是 JSON 对象。这个原则让 CLI-Anything 的命令很容易被其他命令调用也很容易被测试。4. 交互体验让你的命令用起来顺手4.1 彩色输出与终端心智CLI 工具为什么好用的一个关键点是“反馈清晰”。当你敲下一条命令终端滚动输出几十行文字如果没有颜色区分用户必须逐行去读才能找到哪是重点。彩色输出并不是为了好看而是为了“引导视觉”。CLI-Anything 内置了一套基于 chalk 的颜色规范错误用红色、警告用黄色、成功用绿色、流程标题用蓝色辅助信息用灰色。这套规范看似简单但我在实际使用中确实能明显加快信息读取速度。举个我自己的例子一个deploy命令执行过程中会打印步骤名称、编译日志、服务器响应。如果没有颜色所有内容混在一起你要花心思去分辨“哪一步成功、哪一步失败”有了颜色之后一眼扫过来绿色就是成功了、红色就是出错了非常直观。但这里要注意一个细节在有颜色环境里舒适使用不代表在所有环境里都舒适。管道、CI 和编辑器的终端很多不支持 ANSI 颜色所以 CLI-Anything 默认在非 TTY 环境下会自动关闭颜色这个逻辑也可以通过--no-color手动控制。4.2 进度反馈与交互确认命令执行时间有长有短短命令无所谓但长命令没有进度反馈用户会怀疑“是不是卡死了”。CLI-Anything 的插件 API 里提供了一个progress对象算是对批量任务场景的支持。比如要批量上传 100 个文件你可以每上传一个就更新一次进度终端上会显示“12/100 已完成”。这个功能的实现不复杂本质就是利用终端的回车键和覆盖写入但效果非常显著。交互确认则解决的是“危险操作”的问题。比如clean-cache命令会删除本地缓存目录这种操作如果一声不吭地执行用户可能忘记自己曾经敲过这个命令反应过来已经删完了。CLI-Anything 允许在命令描述里声明confirm: 真的要清理全部缓存吗执行时就会先询问用户得到肯定答复后才继续。这个设计在面向生产力场景时必须要有因为命令行的好处是快坏处也是快——快到你来不及后悔。4.3 错误处理与退出码约定关于错误处理我认为“退出码”是 CLI 里最应该规范、却又最容易被忽略的东西。很多手写脚本无论成功失败都是exit(0)这对交互式使用影响不大但一旦挂到 CI 流水线或 shell 脚本里判断“命令是否成功”靠的就是退出码一个错误的 0 会让后面一连串步骤错误地继续往下走。CLI-Anything 里我强制每条命令返回一个退出码0 表示成功1 表示业务错误2 表示参数解析错误。业务错误和参数错误区别对待这样自动化脚本才能采取不同的处理策略。同时错误信息本身也要有结构。不能说一条命令报错就只是控制台打印一行红色文字而要在结构化输出里包含错误码、错误消息、可能的原因和操作建议。CLI 工具做得不好的典型表现是“给你一个孤零零的错误码让你自己去查文档”好的工具应该像朋友一样直接告诉你下一步该怎么办。5. 从零开始的完整实操把一个 API 封装成命令5.1 初始化项目这部分我直接带你走一遍完整流程目标是把和风天气的城市查询接口封装成一条weather命令。选这个例子是因为它足够典型有外部 HTTP 请求、有参数输入、有结构化输出、还有错误处理几乎覆盖了大部分 CLI 场景。首先初始化项目mkdir cli-weather-demo cd cli-weather-demo npm init -y npm install cli-anything安装完成后在项目根目录创建一个commands/目录CLI-Anything 默认会从这个目录加载命令描述文件。5.2 定义命令描述文件新建commands/weather.yaml内容如下name: weather description: 查询指定城市的当前天气 args: - name: city required: true description: 城市拼音或城市 ID例如 beijing - name: days description: 未来几天的预报 default: 1 - name: format description: 输出格式table 或 json default: table action: type: plugin plugin: weather.js这个文件解决的是“命令怎么被调用”的问题包括参数名称、是否必填、默认值。真正干活的逻辑交给插件weather.js。5.3 编写插件逻辑创建commands/weather.js内容是标准的 Node.js 模块const axios require(axios); async function run(ctx) { const { city, days, format } ctx.args; const apiKey ctx.env.WEATHER_API_KEY; if (!apiKey) { throw new Error(缺少 WEATHER_API_KEY 环境变量请先设置); } const url https://api.example.com/v7/weather; const { data } await axios.get(url, { params: { key: apiKey, location: city, days: days } }); const now data.now; const rows [{ 城市: city, 温度: ${now.temp}°C, 天气: now.text, 湿度: ${now.humidity}%, 风速: ${now.windSpeed} km/h }]; ctx.render(rows, { format }); return 0; } module.exports { run };这里的关键点有几个。第一插件接收一个上下文对象ctx里面已经包含了解析好的参数和所有环境变量你不需要自己去解析process.argv。第二错误处理用throw抛出CLI-Anything 会自动捕获并处理用户会看到红色错误信息退出码为 1。第三输出用ctx.render它负责把结构化数据渲染成表格或者 JSON不需要你手动拼字符串。5.4 打包与发布为全局命令在本地能跑通之后把它变成全局命令只需要两步。先在package.json里声明 bin 字段{ bin: { cli-anything: ./bin/cli-anything.js } }然后运行npm link就可以在任意目录下使用weather -c beijing --days 3 --format json这个过程之所以简单是因为 CLI-Anything 本身已经处理好了全局安装时的命令入口、参数解析、帮助文档生成等所有问题。你只需要维护一个 commands 目录每个命令就是一个 YAML 加一个 JS。拿到任何新的项目我通常都会先搭一个这样的骨架后续加命令完全是“复制粘贴再改改”的程度。5.5 让命令可组合最后再提一个 CLI 的进阶玩法命令组合。CLI-Anything 的输出默认支持结构化数据这让你可以把一条命令的结果接进另一条命令的操作里。比如我定义了一个scan命令能列出所有待发布的服务又定义了一个deploy命令可以发布指定服务那我在终端里可以这样写scan --format json | jq .services[] | .name | xargs -I {} cli deploy {}这一行命令做的事相当于“看清有哪些服务、然后挨个发布它们”。这种能力是 GUI 操作很难提供的——在图形界面里你必须一步一步点在 CLI 世界里你可以把命令当乐高积木拼出你想要的行为。而这一切的前提就是输出结构化和标准化的退出码CLI-Anything 在这两条路上已经帮你铺好了地基。6. 常见问题与排查技巧实录6.1 参数解析的边界情况参数解析看起来简单实际用的人多了各种奇怪的输入都会出现。我自己踩过不少坑挑几个典型的说。第一个是“负号开头的值”比如temperature -5解析器很容易把-5当成一个未知选项。解决办法是在定义参数时显式声明allowNegative: true或者强制用户加--分隔符temperature -- -5。第二个是“值中间有空格”比如查询一个带空格的城市名New York如果用户在命令行里不加引号就会被拆成两个参数。第三个是“布尔参数的--no-前缀”这个前面提过但值得再强调一遍如果你提供了一个默认开启的开关一定同时提供关闭它的方式。这些边界情况在图形界面上根本不存在但在 CLI 里很常见。我的建议是在项目早期就把所有参数解析的边界情况列成一个测试清单用自动化测试锁住行为。不然等项目大了你改一行解析逻辑可能会影响到所有命令。6.2 管道与 CI 环境下的输出差异很多命令在终端里运行得很好一接进管道或者 CI 就出问题。最常见的两类一类是颜色代码污染问题本来好看的红绿字在日志文件里变成了一堆[31m这样的转义序列一类是输出到文件时仍然走了表格格式而不是 JSON导致后续程序很难解析。CLI-Anything 给出的方案是默认检测process.stdout.isTTY非 TTY 环境下自动关闭颜色、默认输出 JSON。但这个自动检测也有失灵的时候所以更可靠的做法是显式传--format json --no-color给命令。注意在 CI 流水线里如果遇到输出格式问题第一件事不要改代码逻辑先加上--format json --no-color试一次。多数时候问题只在“输出层”和业务逻辑无关。6.3 跨平台兼容的三个大坑命令行工具最容易忽略的就是跨平台问题。我自己主要开发环境是 macOS但用户里用 Windows 的不少一发布出去就各种报问题。常见的三个坑路径分隔符Windows 用\POSIX 用/拼接路径时要用path.join不要手写字符串。换行符Windows 默认\r\n如果你在命令里用正则匹配文本很容易因为\r匹配不上。环境变量Windows 下通过%VAR%引用POSIX 下是$VARCLI-Anything 插件 API 里统一提供了ctx.env对象就是为了避免你直接操作 shell。解决这些问题没有捷径就是要在设计 API 时就藏好这些系统差异业务代码里不要直接碰系统调用。6.4 命令命名冲突CLI 工具发布出去你精心起的命令名可能已经和系统自带命令、其他工具的命令撞车了。比如我早期做一个工具想让用户用host这个命令调用结果发现host在 Unix 系统里已经存在了而且功能完全不一样。这会让用户非常困惑。我的建议是给命令名加一个独特的前缀比如cla-或者cx-。虽然三个字母的短命令看起来很酷但在真实生产环境里避免命令名冲突比酷更重要。如果确实要用一个短名字可以考虑在安装时询问用户是否需要创建别名而不是默认覆盖。说白了命名是一个工程问题不是审美问题。一个不能稳定依赖的命令名再短再酷也没有用。6.5 常见问题速查表现象可能原因排查/解决办法-5被当成未知选项参数解析器不认识负数显式声明allowNegative: true或用--分隔输出里出现[31m颜色码非 TTY 环境未自动关闭颜色显式加--no-color参数Windows 下路径拼接错误手写字符串拼接分隔符改用path.join不要手动加斜杠CI 里命令报错但退出码为 0脚本未正确传播错误检查插件是否返回非零退出码--help里有中文字段乱码终端编码不是 UTF-8Windows 下执行chcp 65001切换 UTF-8插件找不到模块NODE_PATH设置不正确用绝对路径或打包场景优先选择 ncc/webpack 等方案命令名和系统命令冲突全局命令重名增加前缀或安装时提示别名结尾一句大实话如果你问我做 CLI-Anything 最大的收获是什么我的回答不是代码本身而是“把工具做顺手”带来的长期回报。命令行工具最大的特点就是“复利效应”——每一次把它打磨好后续的每一天你都会重复使用它省下的时间会像滚雪球一样越滚越大。我个人现在的习惯是凡是需要做第二次的重复操作一定会停下来想能不能把它做成一个命令如果能就立刻动手。这种习惯可能不会让你一天省下很多时间但一年下来真的很可观。另外分享一个实用一点的小技巧你做的第一个命令永远不要试图覆盖太复杂的场景从一个输入参数、一个输出结果的小功能开始就好。等这个命令真正用顺手了你自然会知道它哪里该加参数、哪里该拆子命令到时候再迭代方向感会清晰得多。
