CLI-Anything：一个将任意操作封装为命令行命令的配置驱动框架

1. 从“重复操作让人崩溃”到“所有事情都塞进命令行”1.1 我的日常工作痛点去年夏天我给自己定了一个有点奇怪的规矩凡是每周要重复做三次以上的操作都必须想办法用命令行完成。听起来像自找麻烦可坚持两三个月后我电脑上的命令越来越多从图片压缩、批量重命名到查天气、调内部接口全靠一串串记不完的参数。直到有一天我实在受不了动手写了个小工具把散落各处的命令和脚本统一管理起来。它就是我后来一直在维护的 CLI-Anything——一个把“Anything to CLI”落地的通用命令封装框架。我日常的工作里重复性最高的不是写代码而是那些夹在代码之间的“杂活”。比如给博客配图我要先截图、然后拖进压缩软件、再手动转成 WebP、最后回文章里替换文件名比如测后端接口我得先拼接 URL、填 token、看返回的 JSON再把关键字段挑出来看再比如每周备份日志备份完还要清理三天前的临时文件。这些事情单独看都不难但每次都要重新打开对应的图形界面、回忆参数、确认步骤出错率一点不低。问题在于这些操作“不可记录、不可复用、容易漏步骤”。图形界面做得再漂亮也没法让你一条命令把截图、压缩、改名、替换一次做完。而我虽然会写 shell 脚本但每个脚本的参数、路径、依赖库都不一样时间一长脚本本身就成了新的负担。1.2 CLI-Anything 到底想解决什么CLI-Anything 最开始并不是一个计划好的项目。我只是想找一个“命令的管理器”把零散的单条命令和脚本串起来统一用一套规则描述。现在它的定位很明确不是某一个具体功能的命令行程序而是“命令的编排器”。这里的 Anything 包含了三个层面。第一任意可执行对象它不但可以运行本地 shell 命令也可以调用外部脚本、发起 HTTP 请求甚至按需执行一段 JavaScript 或 Python 代码。第二任意参数输入它支持命令行参数、环境变量、配置文件里的默认值以及上一步执行后的输出结果作为下一步的输入。第三任意组织方式一条命令可以简单到只打印一句话也可以复杂成一个多步骤的流水线比如先拉取数据再处理文本最后推送通知。所以CLI-Anything 解决的核心问题不是“命令行比鼠标快”而是“把你的操作变成可描述、可复用、可分享的配置”。我只需要在一个 YAML 文件里写清楚这个命令接收什么参数、执行哪些步骤剩下的事情都由它去调度。这才是“Anything to CLI”的真正含义。1.3 它和你平常用的单点工具差在哪很多人觉得命令行工具早就有了curl、jq、ImageMagick、ffmpeg哪一个不是命令行确实单点工具能力很强但它们解决的是“单件事”比如 curl 负责发请求jq 负责解析 JSON。CLI-Anything 更像是站在这些工具的上层负责把它们的参数统一、把执行顺序编排起来。对比项单独命令curl / jq / cwebpCLI-Anything参数要不要记每个工具语法各不相同记不住就翻文档参数统一写在 YAML 声明里--help自动生成多步骤串联要自己写 shell 脚本容易处理不了各种边界配置里声明步骤自动串联前一步输出可作为后一步输入是否方便分享脚本贴到聊天工具里格式乱还容易贴错一个配置文件就是一个命令Git 仓库即可管理学习成本每个工具一套文档长期学习成本很高只需要学一种配置格式内部调用的还是你熟悉的命令我并不是让你抛弃 curl 和 jq恰恰相反CLI-Anything 内部执行的大多数步骤仍然是这些“老家伙”。它做的是最外围的那一层封装让使用者只记cli-anything 项目名 动作名具体的参数名、默认值、执行顺序都交给配置。2. 核心机制拆解一条 cli-anything 命令背后到底发生了什么2.1 一条命令的执行链路我用一个真实场景来说明。假设你执行了cli-anything images compress --src ./photos --quality 80CLI-Anything 拿到这串输入后内部会按六个阶段处理。先解析子命令路径也就是images compress去commands/images.yaml里找到compress这个命令。然后把--src和--quality解析成两个变量src./photos、quality80。接着做必填参数校验如果src没传工具会直接打印用法说明并退出不会进入执行阶段。校验通过后进入模板渲染阶段把配置文件中所有的{{src}}和{{quality}}占位符替换成刚才解析到的值。替换完成后再按顺序执行steps列表支持run执行 shell 命令、http发起请求、script运行多行脚本。最后在每个步骤结束后记录退出码、耗时和关键输出方便排查问题。设计这个流程时我最坚持的一点是模板渲染必须在 shell 执行之前完成。因为配置里写的是人话使用者只需要关心占位符能不能被正确替换不需要关心命令内部的引号和转义规则。等到真正执行时看到的已经是一份完整的、可以直接运行的命令文本。2.2 配置文件的三个核心字段一个最小的命令配置通常长这样name: images description: 图片处理相关命令 commands: compress: description: 批量压缩图片 parameters: - name: src required: true description: 图片来源目录 - name: quality default: 80 steps: - run: - find {{src}} -maxdepth 1 -type f \( -name *.png -o -name *.jpg \)parameters声明这个命令接收哪些参数。每个参数要有name可以声明required和default建议补上description因为后面生成--help提示时会用到。steps是执行序列数组里的每一项按顺序执行常见的三种类型是run、script和http。run适合单条命令script适合多行逻辑http适合调用接口。commands外围还可以挂name和description这对应的是命令分组。我习惯把“图片处理”相关的命令都放在一个images.yaml里把“天气查询”相关命令放在weather.yaml里这样cli-anything images可以作为一组子命令统一管理不会把所有功能堆在一个巨型文件里。2.3 参数注入与模板渲染的边界模板占位符我统一约定为{{变量名}}而不是 shell 常用的$变量名。这个约定非常重要。如果你用$配置里的很多内容会被当前 shell 优先展开比如你写echo 价格是$price还没轮到 CLI-Anything 处理$price就已经被外层 shell 替成了空字符串。而{{ }}在 bash 和 zsh 里都不是特殊字符可以在整个配置流程中安全传递。变量来源有三个。一是命令行参数也就是--src ./photos这种二是环境变量写法是{{env.API_KEY}}工具在启动时会读当前环境三是上一步的输出通过capture字段把命令输出的内容存成一个变量给后面的步骤引用。比如先执行find获取文件列表再用capture: file_list把它存起来接下来的script步骤里就能读取{{file_list}}。还有一点很多初学者会忽略环境变量不要直接写进配置文件。尤其是 API Key、密码之类的敏感信息配置文件通常会进 Git 仓库一不小心就泄露了。正确做法是只在配置里写{{env.API_KEY}}具体值保存在本机的.env或 shell 配置文件里。CLI-Anything 启动时会先做一次环境变量解析如果发现必填的环境变量缺失会明确报错而不是静默执行。3. 半小时搭好第一个版本环境准备与最小可用配置3.1 运行环境准备CLI-Anything 基于 Node.js 18 以上版本构建安装很简单npm install -g cli-anything cli-anything initinit会在~/.cli-anything/目录下生成config.yaml主配置文件和commands/子目录。选择 Node.js 而不是 Python 或 Go主要是因为它的跨平台支持好、YAML 解析和模板渲染生态成熟而且fetch功能在 18 版本之后已经原生内置不需要额外引入请求库。如果你更熟悉 Python其实实现思路完全一样。关键不是语言而是“配置驱动”这个理念命令怎么执行、参数怎么绑定、步骤怎么串联全部由配置文件描述而不是把逻辑写死在代码里。这样你想加一个命令不需要改主程序只需要往commands/目录丢一个新的 YAML 文件。3.2 编写第一条命令配置初始化完成后在commands/目录里创建一个hello.yamlname: hello description: 和你打招呼 commands: greet: description: 输出一句问候 parameters: - name: name required: false default: 朋友 steps: - script: | echo 你好{{name}} echo 当前时间是 $(date)然后执行cli-anything hello greet --name 小明输出大致是你好小明 当前时间是 2025年 7月 1日 星期二 10时23分45秒 CST这个最小配置已经覆盖了三个核心概念参数默认值、模板渲染、多行脚本执行。script块里的$(date)是 shell 自带的命令替换它会在脚本执行时被解析和 CLI-Anything 的模板系统互不干扰。这一点我一开始没搞清楚后面在踩坑清单里会详细讲。3.3 验证命令是否生效写完配置后可以用cli-anything list查看当前已经注册的所有命令分组用cli-anything hello greet --help查看参数说明。如果第一次运行就报了command not found多半是 npm 的全局 bin 目录没有加进 PATH。用npm config get prefix查一下安装前缀再把对应的bin目录写进.bashrc或.zshrc即可。CLI-Anything 内置了一个--dry-run参数在任何命令后面加它工具只会完成参数解析和模板渲染打印出真正要执行的命令内容但不会真正运行。这个功能在调试模板渲染时特别有用。比如你觉得{{src}}的值不对先跑一遍 dry-run看看替换后的命令文本长什么样比直接在线上环境误运行安全得多。4. 跑真实项目三个我每天都在用的配置4.1 批量压缩图片并生成 WebP 预览我的博客配图流程是把截图丢进一个目录然后压缩成 WebP 格式。手动操作至少三步开了界面还要等预览。用 CLI-Anything 之后我把这套流程写成了一个命令name: images description: 图片处理相关命令 commands: optimize: description: 将指定目录下的 jpg/png 转为 webp 并输出处理结果 parameters: - name: src required: true description: 图片来源目录 - name: quality default: 80 steps: - run: - find {{src}} -maxdepth 1 -type f \( -name *.png -o -name *.jpg \) capture: source_files - script: | mkdir -p {{src}}/webp count0 for f in {{source_files}}; do cwebp -q {{quality}} $f -o {{src}}/webp/$(basename ${f%.*}.webp) count$((count 1)) done echo 处理完成共 $count 个文件有人会问为什么用find而不是 shell 的通配符*.jpg。原因是通配符在目录为空时会原样保留*.jpg字符串传给命令导致 cwebp 报错而且文件名含空格时通配符展开也会出问题。find配合后面的$f双引号能同时规避这两个问题。我建议把quality设成有默认值而不是每次调用都传。因为对不同需求80 是相对通用的选择。如果某批图片需要更高清再临时用--quality 90覆盖默认值。4.2 把 API 接口变成命令行子命令开发时我经常要测一个天气服务的接口每次都写一遍几十个字符的 curl 很烦。封装成 CLI-Anything 命令之后直接查城市名就够了name: weather description: 天气查询 commands: now: description: 查询指定城市的实时天气 parameters: - name: city required: true steps: - http: method: GET url: https://api.example.com/v1/weather query: city: {{city}} key: {{env.WEATHER_API_KEY}} capture: response - run: - echo {{response}} | jq {city: .location.name, temp: .current.temp_c, text: .current.condition.text}http这个步骤类型是 CLI-Anything 内置的底层封装了 Node.js 的 fetch。它可以自动把响应存到capture指定的变量里如果返回的是 JSONCLI-Anything 还会帮你解析好直接用 jq 就能提取字段。请注意这里用到的域名api.example.com是示例实际使用时替换成你自己的服务地址。API Key 通过{{env.WEATHER_API_KEY}}从环境变量读取环境变量的值在本机设置。这样配置文件即使传到 Git 仓库里也不会泄露任何密钥。如果你把配置发给团队成员对方只需要在自己的环境里配置好WEATHER_API_KEY就能直接使用。4.3 定时清理本地临时文件这台开发机的/tmp目录下有各种缓存文件每周不清理就会占用好几个 G。手动清理的问题是rm -rf一旦指错目录后果很严重所以我给它加了一个--dry_run开关默认安全模式name: cleanup description: 清理临时文件 commands: tmp: description: 清理指定目录下超过 N 天的文件 parameters: - name: dir default: /tmp - name: days default: 3 - name: dry_run default: true type: boolean steps: - run: find {{dir}} -type f -mtime {{days}} capture: old_files - script: | if [ {{dry_run}} true ]; then echo 以下文件将被删除 echo {{old_files}} else echo {{old_files}} | xargs -r rm -v fi第一次执行时我用默认的dry_runtrue先跑一遍确认列出的文件都是没用的缓存然后才手动改成--dry_run false真正清理。后来配合系统的定时任务每周五下班前自动执行一次已经跑了大半年没出过事。有一点要注意xargs -r这个参数在 Linux 上没问题但 macOS 自带的 BSD xargs 不支持-r会报“未识别的参数”。如果你在 macOS 上运行把-r去掉然后通过判断{{old_files}}是否为空来避免执行空命令。5. 踩坑清单我实际用下来最痛的五类问题5.1 文件名带空格命令被拆得七零八落这是所有把命令拼成字符串的工具最容易踩的坑。比如你写cli-anything images optimize --src ./backup 2024如果底层用shell模式去拼接并执行整个字符串./backup和2024会被识别成两个参数命令直接找不到目录。CLI-Anything 处理这个问题的方式是双保险第一在script块里要求所有引用变量的地方都用双引号包裹比如$f第二当参数值是字符串数组时底层用spawn而不是shell不会因为空格而产生二次分词。我的习惯是只要涉及文件路径一律在 YAML 配置中写双引号不管这个路径看起来多“干净”。多写一对引号换来的是一次少调试十分钟。5.2 模板渲染与 Shell 转义的双重生效这个坑非常隐蔽。假设你想打印一个 shell 变量steps: - script: | price98 echo 商品价格是 $price你预期输出“商品价格是 98”实际却可能输出“商品价格是”。原因在于CLI-Anything 的模板引擎允许两种占位符一种是{{变量}}一种是${变量}。$price被模板引擎当成了自己的变量来解析但这个变量不存在于是替换成了空字符串等到真正执行 shell 脚本时$price已经不存在了。我后来统一了规则CLI-Anything 的模板占位符只认{{ }}其他$开头的变量统统原样保留交给最后的 shell 去处理。如果你正在设计自己的版本务必把模板引擎和 shell 执行两层的替换时机拆清楚不要混在一起。5.3 sudo 执行时找不到配置和命令有段时间我需要在服务器上清理系统日志习惯性地加sudo执行sudo cli-anything cleanup tmp --dry_run false结果发现配置目录完全找不到。原因很简单默认配置在~/.cli-anything/而 sudo 会把$HOME切换成/root甚至在某些系统上直接重置环境变量导致 CLI-Anything 跑到/root/.cli-anything/去找配置当然找不到。解决方案有三个。第一种不给整个工具加 sudo而是在步骤内部的特定命令前加 sudo比如sudo rm -f {{old_files}}第二种设置CLI_ANYTHING_HOME环境变量指向你的配置目录这样无论当前用户是谁都能找到同一份配置。第三种也是最推荐的不要直接在你的业务机器上用 sudo 跑这类自动清理任务而是让定时服务以独立用户身份运行权限边界清晰得多。5.4 并发执行两个任务输出日志混在一起CLI-Anything 支持同时开多个终端跑不同命令。我第一次同时跑图片压缩和天气查询时两个任务的输出混在一起根本分不清哪行属于哪个任务。后来发现工具提供了-v详细模式打开后每行输出都会带时间戳和命令名另外每个命令也可以指定log_file把输出重定向到独立文件steps: - run: find ... log_file: /tmp/cli-anything-images.log如果你的命令本身有长时间运行的步骤我建议从一开始就为它配置独立的日志文件。这样即使出错也不用从混合输出里大海捞针。5.5 跨平台路径与命令的差异CLI-Anything 跨平台跑的时候最烦的是路径分隔符。Windows 的路径是C:\Users\xxx\photos在 YAML 双引号里反斜杠必须转义写起来很痛苦。我的经验是所有配置文件里统一使用正斜杠C:/Users/xxx/photos。Windows 的大部分命令和 Node.js 都能正常识别。更大的问题是命令本身的差异。图片压缩需要cwebp清理任务需要find这些在 Windows 上要么没有要么行为不同。为此 CLI-Anything 在模板变量里内置了{{os}}配置中可以按平台分支steps: - script: | if [ {{os}} windows ]; then where cwebp else which cwebp fi真实项目里我很少为了“一个命令全平台可用”而写太多分支。多数时候团队内部会约定主力平台是 Linux 还是 macOSWindows 机器只处理那些与平台无关的简单命令。这样既控制了复杂度也不会让配置文件变得难以维护。6. 进阶从个人玩具到团队命令中心6.1 用 Git 管理配置让命令成为团队资产当commands/目录里的文件超过十个手动维护就开始吃力了。我把它做成一个 Git 仓库在团队内部共享。每个新增命令必须满足两个硬性要求description必须写清楚用途和典型用法参数不能超过五个。超出五个说明这个命令的职责太杂应该拆分成两个。目录结构按团队职能来分~/.cli-anything/ ├── config.yaml └── commands/ ├── frontend/ │ ├── images.yaml │ └── deps.yaml ├── ops/ │ ├── cleanup.yaml │ └── deploy.yaml └── common/ └── utils.yaml新同事入职后只需要把仓库 clone 到~/.cli-anything/再跑一次cli-anything sync就能拥有团队全部命令。相比把脚本发来发去这种方式最大的好处是所有命令的说明、参数、更新记录都留在代码仓库里审阅和回溯都非常自然。6.2 自动补全脚本让命令真正好用命令一多记参数名也是负担。CLI-Anything 提供completion子命令可以直接生成 shell 补全脚本source (cli-anything completion bash)这个补全脚本不是手工维护的而是每次启动时解析所有配置文件里的parameter.name自动生成候选。比如配置文件里有quality参数你敲cli-anything images optimize --qu再按 Tab它就能补全成--quality。我建议把source那行写进.bashrc或.zshrc这样每次开终端都是现成的。刚开始可能会觉得补全依赖只在命令行工具里才有价值但真当你手边同时开五个终端窗口时少记一个参数名就是少一次翻文档的时间。6.3 “Anything”的边界有些事别硬塞进命令行很多朋友看到这类工具第一反应是要把所有操作都塞进 CLI我觉得有必要泼一盆冷水。有几种场景真的不适合需要频繁交互和可视化确认的操作比如裁剪图片时要实时看预览你用命令行做会很痛苦一次性的复杂操作不值得为了它写一个配置还有一些强调手感、实时反馈的工具比如图形化编辑器命令行再怎么封装也替代不了。而且封装也是有成本的。一个命令如果每次使用的频率低于每周一次你写配置和调参数的时间可能比手动操作还长。我的经验是同一个步骤重复到第三次才值得把它做成配置。第一次和第二次先手动跑跑的过程顺便把操作步骤记录下来等第三次要做时这份记录自然就变成了 YAML 配置的草稿。用 CLI-Anything 快一年最大的收获不是省下了多少秒而是它逼着我在动手做重复事之前先想清楚“这个操作能不能被描述成参数和步骤”。很多原本觉得“太琐碎没法自动化”的事其实拆解下来也就两三个变量真正麻烦的只是第一步——坐下来把流程写出来。如果你也想动手整理自己的命令库听我一句劝不要一开始就规划几十个场景挑一个你每周至少做三次的操作先写出第一个配置然后慢慢加。等你的commands目录超过十个文件时自然就明白哪里该用参数、哪里该拆步骤。到那时候你会发现自己已经不太需要依赖某个具体工具了因为每个坐在电脑前的人都能把重复的事情变成自己的“Anything”。