我把自己所有的日常工具都折腾成了命令行工具之后最近又被一个叫CLI-Anything的项目勾起了兴趣。说白了这个项目的野心就是把任何东西都变成命令行工具。不管是一个内部 API、一段 Python 脚本、一个 LLM 模型接口还是一个需要频繁操作的数据库查询你都可以用一套声明式的配置快速封装出一个符合 Unix 哲学、支持自动补全、统一参数校验的 CLI。先说说它适合谁。如果你平时要写一堆一次性脚本每次都要处理 argparse、点击Click的参数解析、环境变量加载、错误输出格式那 CLI-Anything 能把这套重复劳动直接砍掉。如果你想给团队暴露一个内部服务但不想专门开发一个 Web 控制台用 CLI 反而更符合工程师的操作习惯。这篇文章我会从整体设计思路、配置解析、实操封装流程、常见问题排查四个维度展开全程基于我自己的实际使用经验尽量把「为什么这么做」讲透。1. 整体设计思路为什么说 CLI-Anything 是“工具箱里的最后一颗螺丝”1.1 它解决的根本问题工具碎片化我见过太多团队内部工具散落在各种地方有人写了个 Python 脚本在服务器上跑有人封装了个 Web 页面但端口老是忘有人把常用 SQL 存在 Notes 里每次复制出来手动改参数。这些东西的共同痛点是没有统一的入口、没有统一的参数规范、没有统一的输出格式。CLI-Anything 的思路就是把这些东西全部收敛到命令行。你只需要定义一个 manifest清单文件描述这个工具叫什么、接收哪些参数、调用什么后端逻辑CLI-Anything 会自动生成一个标准命令行程序。这个程序的行为跟原生 CLI 一致支持--help、支持 TAB 补全、支持参数类型校验、支持输出格式化。对于团队来说所有人都在同一个终端里使用同一套工具学习成本几乎为零。1.2 它的核心哲学约定优于配置我第一次看到 CLI-Anything 的配置方式时第一反应是“这不就是写个 JSON 吗”。但真正用下来才发现它最大的价值在于强制你按照一套约定来组织工具描述。比如参数定义遵循 JSON Schema 风格有type、description、default、required这些字段后端执行逻辑可以是内置的 HTTP 适配器、数据库适配器、Shell 命令适配器也可以是你自己写的一个可执行程序。这套约定带来几个实实在在的好处。第一参数校验不需要你写代码CLI-Anything 会根据类型定义自动拦截非法输入。第二帮助文本和自动补全是自动生成的你不用再手动维护 README 里的命令示例。第三工具的接缝非常清晰哪天后端服务换了地址只改配置不改客户端代码。对比下来传统的 argparse 方案就像你每次建房子都从搬砖开始而 CLI-Anything 给你的是一套预制好的框架你只需要填墙体。1.3 它与同类方案的区别从“写代码”变成“描述行为”传统的 CLI 开发栈无非是 argparse、Click、Commander.js 这类库。它们的特点是你需要写代码来定义参数、写逻辑、处理异常。CLI-Anything 走的是另一条路它要求你描述“这个工具长什么样”和“它应该怎么工作”然后由一个运行时引擎来统一执行。这个区别在维护场景下体现得最明显。我用 Click 写过不少工具每次加一个参数要么改函数签名、要么改装饰器改完还要跑一遍测试确认没有破坏其他参数。用 CLI-Anything 加参数就是改配置里的一个字段核心执行逻辑完全不用动。而且CLI-Anything 天然支持多语言后端你不需要因为换了一个微服务的实现语言而重写命令行入口。这是它作为“胶水层”的最大意义。1.4 项目模块组成CLI-Anything 通常包含这几个核心模块配置解析器读取 manifest、合并默认值、支持环境变量覆盖、动态参数构建器把配置转换为符合用户预期的 argparse 或 Commander 风格参数、执行引擎调度适配器、处理超时、捕获退出码、输出格式化器支持纯文本、JSON、Table 等输出格式、插件系统允许你注册自定义适配器和自定义验证规则。理解这个模块划分后你就不太会被它庞大的文档吓到了因为绝大多数时候你只需要关心 manifest 怎么写。2. 核心配置解析manifest 文件的每一个关键字段2.1 manifest 的顶层结构CLI-Anything 的配置文件一般命名为cli.yaml或cli.json我习惯用 YAML原因只有一个支持注释。配置顶层分成几个主要部分tool工具元信息、parameters参数定义、runner执行方式、output输出规则。一个最小可用的cli.yaml差不多长这样tool: name: weather-cli version: 1.0.0 description: 查询指定城市的实时天气 parameters: - name: city type: string required: true description: 城市名称例如北京 - name: unit type: string default: celsius enum: [celsius, fahrenheit] description: 温度单位 runner: type: http url: https://api.example.com/weather method: GET headers: X-API-Key: ${API_KEY} query: city: {city} unit: {unit} output: format: table fields: [city, temperature, unit]这段配置基本上就是在说我有一个叫weather-cli的命令它接收两个参数一个必填的城市名一个可选的温度单位实际执行的时候它会去请求一个 HTTP API然后把返回结果按表格输出。整个过程没有写一行 Python 或 Node.js 代码。2.2 参数定义的核心字段与验证机制在参数定义部分type字段支持的类型通常包括string、integer、number、boolean、array、object等。这里有个容易忽略的细节CLI-Anything 的array类型默认支持两种传法一种是逗号分隔如--tags a,b,c另一种是重复传参如--tags a --tags b。你可以在参数配置里用style字段指定默认推荐前者在 shell 里用起来更顺。除了常规的required和default我强烈建议多用enum。表面上它只是限制输入范围实际上它同时生成了自动补全的候选列表。也就是说当用户敲--unit后按 TABCLI-Anything 会根据 enum 值补全出celsius和fahrenheit。这种体验是普通脚本永远给不了的。参数之间还支持隐式依赖比如parameters下的dependencies字段可以声明“如果传了 A则 B 必填”。这个功能一开始我觉得鸡肋后来发现它特别适合那种既支持简单模式又支持高级模式的命令比如不传--config时就用默认配置传了就必须要带上--env。2.3 runner 适配器决定“命令到底怎么执行”runner 是整个配置的灵魂。我实际用下来内置适配器里使用频率从高到低是HTTP、Shell、file、script 和 custom。下面逐个展开。HTTP 适配器用来请求 REST API它支持自定义请求头、query 参数、JSON body也能在响应后用output里的字段做映射。Shell 适配器适合包装系统命令比如把kubectl get pods包装成一个更简单的kubectl-cli pods这时你只需要配置command模板和参数占位符。file 适配器处理本地文件读写适合那些“读取状态文件并获取信息”的工具。script 适配器负责执行本地脚本并捕获输出这是扩展性最强的入口。custom 适配器是最后一张牌你可以用任意语言写一个子进程只要它满足约定从 stdin 读入一个 JSON包含所有参数在 stdout 输出一个 JSON包含结果。这个设计的妙处在于它把所有语言都限制到了“读入 JSON、写出 JSON”的窄缝里保证了任何语言写的后端逻辑都能无缝接入。我曾写过一个小工具后端是 Rust 做的文本处理custom 适配器跑得干干净净完全不需要处理命令行参数的转义问题。2.4 认证与敏感信息管理CLI-Anything 的配置里可以直接写 API Key 吗可以但不推荐。它支持引用环境变量的语法${VAR_NAME}加载配置时自动从当前环境展开。另外它还支持嵌套密钥的方式比如db: { user: ${DB_USER}, password: ${DB_PASSWORD} }这对数据库类的工具非常友好。有一点要注意CLI-Anything 在展示--help的时候不会展开环境变量它打印配置模板里的原始占位符。这意味着同事之间分享一个cli.yaml不会泄密。但 CI 环境里用的时候你得确保变量已注入到进程中否则命令会以一个空值发起请求排查起来挺费劲。遇到这种情况我会习惯性地先跑一条env | grep API确认环境。2.5 输出格式化的取舍output部分决定用户看到的最终结果。CLI-Anything 内置了几种格式纯文本、JSON、Table、CSV。我的经验是默认格式最佳选择是 Table因为它不需要额外工具就能直接看但在脚本场景下用--output json配合 jq 做进一步处理反而更香。接下来有个细节很容易踩坑Table 格式的列宽计算依赖中文字符。CLI-Anything 对中文宽度做了处理但如果你在title里用了 emoji 或特殊符号表格对不齐的情况还是会偶发。官方建议列标题尽量用纯英文如果团队需要中文就用fields的label字段单独指定显示名这比直接写中文更稳。3. 实操全流程三步封装一个“任何东西”3.1 把内部 HTTP API 封装成团队命令行工具我找一个具体场景来演示假设你们公司有个内部服务可以根据员工 ID 查排班信息。原来的方式是登录内部后台手动输入 ID然后盯着网页看表格。现在我要用 CLI-Anything 把它封装成schedule-cli get --id 9527。先创建 manifest 文件tool: name: schedule-cli version: 1.0.0 description: 查询员工排班信息 parameters: - name: id type: integer required: true description: 员工 ID - name: date type: string required: false description: 查询日期格式 YYYY-MM-DD默认今天 runner: type: http url: https://internal.example.com/api/schedule method: GET headers: Authorization: Bearer ${SCHEDULE_TOKEN} query: employee_id: {id} date: {date} output: format: table fields: - name: shift label: 班次 - name: start label: 开始时间 - name: end label: 结束时间然后在项目目录下执行安装命令。CLI-Anything 会解析配置、生成可执行文件、注册到 PATH。装好后在终端敲schedule-cli get --id 9527 --date 2024-06-15它会先把参数校验一遍比如 ID 必须是整数date 若是非法的格式则直接报错然后向内部服务发起请求最终输出一张对齐的班次表格。这个流程里最爽的是如果你传了--helpCLI-Anything 会自动生成完整帮助文档连参数的默认值都给标注出来。这样你就不用再单独维护一份 README 作为命令手册了。当你往团队其他同事手里推送这份cli.yaml时不需要告诉他们怎么装 Python 依赖、怎么配环境变量他们只要装了 CLI-Anything 这一个运行时就行。3.2 将 Shell 命令或本地脚本包装成统一入口还有一类更常见的需求是把一堆零散的系统命令收敛起来。我们团队过去有个痛点每天都要连上不同服务器执行同样的排查命令每个环境的连接方式还不一样。后来我把这些命令全部封装到一个ops-cli里。配置里 runner 用的是 shell 类型runner: type: shell command: ssh {user}{host} df -h free -m uptime参数部分就定义user、host以及一个sudo布尔参数。当sudo为 true 时命令模板变成echo {password} | sudo -S ...这类带提权的逻辑。这里我踩过一个坑命令模板里的占位符如果值包含空格shell 适配器不会自动加引号你需要在模板里自己补上引号就像上面{user}的处理方式。特别是当user的值来自外部环境变量时不加引号极容易导致 SSH 命令解析错乱。如果你要封装的不是单个命令而是一个多步骤脚本那么 script 适配器会更适合。你只需要指向一个脚本路径CLI-Anything 会把所有参数转成环境变量比如PARAM_FOOvalue传入脚本内部直接读取这些环境变量。这个方式的优势是不用考虑参数引号转义问题脚本里你想怎么写就怎么写。我个人很喜欢把“数据采集加解析”这种逻辑写在 Python 脚本中然后套一层 CLI-Anything稳得很。3.3 把 LLM 接口封装成可交互的命令行最后演示一个现在特别流行的场景把大模型接口封装成一个 CLI。CLI-Anything 官方有一个 LLM 适配器但也支持用 HTTP 适配器直接实现。我以调用一个兼容 OpenAI 格式的接口为例tool: name: ai-cli description: 向大模型发送一条消息并返回回复 parameters: - name: prompt type: string required: true description: 用户输入的内容 - name: system type: string default: You are a helpful assistant. description: 系统提示词 runner: type: http url: https://api.example.com/v1/chat/completions method: POST headers: Authorization: Bearer ${LLM_API_KEY} Content-Type: application/json json: model: gpt-4o-mini messages: - role: system content: {system} - role: user content: {prompt} temperature: 0.7 response_path: choices.0.message.content output: format: text这个配置的亮点在response_path它从返回的嵌套 JSON 中精准提取出choices[0].message.content字段用户看到的就是大模型的回复文本完全不用自己解析响应体。我实际用了一阵子发现把 LLM 封装成 CLI 的价值被严重低估了。比如我可以直接在一个管道里运行cat server.log | grep ERROR | head -n 20 | ai-cli 帮我总结这段日志的关键错误。这比打开网页版聊天工具再复制粘贴日志高效一个量级。而且因为所有参数都走命令行自动补全和--help依旧有效团队的 AI 工具使用门槛一下子就拉低了。3.4 安装部署细节与 Windows 兼容性CLI-Anything 的安装方式在官方文档里写得很清楚但我补充两个个人心得。第一建议安装到一个独立目录比如~/.cli-anything/clis然后把这个目录加到 PATH 里。这样升级 CLI-Anything 本身不会影响已生成命令。第二Windows 环境下很多 shell 风格的环境变量扩展示例不适用我在 PowerShell 里就撞过墙。解决办法是让配置里统一使用 CLI-Anything 的${VAR}语法而不要混用 Windows 的$env:VAR因为适配器内部有跨平台的变量查找逻辑混用容易出现一边可用一边不可用的情况。生成的命令行程序还有一个按键补全的额外动作。它启动时会检查你的 shell 类型生成对应的补全脚本。如果你是 bash它会加一段complete -C脚本如果是 zsh则加compdef。我测试过在 fish shell 里也能工作不过你需要在安装之后重启一次 shell或者手动加载对应补全文件。大部分用户的注意点都放在“怎么让命令跑起来”而我更关注“跑起来之后能不能按 TAB 补全”因为这才是命令行工具相比 Web 端最大的效率红利。4. 常见问题与排查技巧避坑记录4.1 参数占位符没替换遇到比较多的一个报错是请求发出去之后服务端返回 400而日志里显示的是一条带着{city}字样的请求 URL。这个情况九成是参数占位符没被适配器识别。可能的坑位有两个一是占位符里的名字和参数定义的大小写不一致CLI-Anything 是严格区分大小写的二是你用了 YAML 里不规范的引号写法导致占位符被当成普通字符串。排查方法其实很简单先跑一次cli-name --debug或者设置环境变量CLI_ANYTHING_DEBUGtrue它会打印出适配器渲染后的完整请求参数。看到渲染结果的那一刻问题就一览无余了。如果还不行我建议拿一个没有歧义的参数做最小化测例比如只有一个 string 参数逐个确认是不是多参数拼接时的渲染问题。4.2 enum 校验太严格用户想传别名怎么办CLI-Anything 的 enum 校验是字面量匹配意味着--status success和--status SUCCESS是两种不同的值。有次我们想定义一个命令支持日志级别枚举了debug/info/error结果有同事按习惯传了ERROR直接被拒了。当时有两种改法一种是把枚举值全改成大写但这样跟配置里的其他工具风格不统一另一种是启用参数的normalize字段设置case: lower或case: upper让输入先规范再校验。我后来统一给这类参数加了规格化声明效果很好团队成员不需要追着完全一致的字符串格式。这里我个人的建议是在设计 enum 参数时就预料到大小写混用并做归一化处理。不要过分信任用户输入习惯命令行工具的体验差异往往就藏在这些边界情况里。4.3 输出表格乱码或列错位中文内容多的表格偶尔会出现列错位看起来像是表格没有对齐其实是列宽计算逻辑在中英混排下的老问题。CLI-Anything 在计算列宽时会区分全角半角字符但如果你用的终端字体在渲染某些特殊符号比如→、≈时宽度不对界面就会乱。最省心的处理方案是在output里把这类字段设为truncate: true用省略号截断过长内容或者干脆让该命令默认输出 JSON再配合 jq 做后续格式化。不是非得所有命令都用 Table 一根筋走到黑。4.4 命令明明正确但 shell 补全不起作用这类问题的排查方向基本就两个一是补全脚本路径没挂上尤其是当 PATH 里有多个版本的 CLI-Anything 时新生成的命令可能被旧命令抢占了complete定义二是 shell 缓存了旧的补全策略bash 的hash -r可以清一下。若是 zsh可以运行compinit强制刷新。另外注意一点CLI-Anything 生成的补全脚本有一些依赖子命令关键词比如get、set如果你把description写得很长在某些 shell 实现里 TAB 补全列表会拉的特别宽。别问我怎么知道的调了半小时才明白是描述文本太长导致视觉上以为没触发补全。4.5 适配器执行超时的处理CLI-Anything 默认超时时间一般是 30 秒。在数据库类或 LLM 类命令里30 秒经常不够。此时在 runner 里显式设置超时时间runner: type: http timeout: 120这个细节我几乎逢人就提因为 LLM 接口的响应速度经常抽风默认超时会让用户莫名其妙看到一个 timeout 错误而不是一个正常返回。调成 120 秒之后体验会舒服很多。如果你还想要更细的控制CLI-Anything 支持独立的connect_timeout和read_timeout网络诊断场景里很有用。4.6 版本升级带来的兼容性问题CLI-Anything 更新比较频繁有一次我从 0.3.x 升到 0.4.x发现原有配置里http.headers下的模板字符串${API_KEY}不再生效必须改为env: API_KEY这种最新语法。这属于破坏性更新升级前最好对现有 manifest 做一次cli-anything validate检查。官方也提供了旧配置迁移工具但我的经验是先把配置文件备份再跑迁移器再人工检查 diff最后再删除备份。如果你在团队里推广 CLI-Anything建议在仓库里锁版本比如在cli-anything config set auto_update false。命令行工具和前端库不一样没有浏览器帮你兜底配置可能因为一次升级全部失灵保守一点没坏处。收个尾一些还热乎的经验要我说CLI-Anything 最有魅力的地方不是它省了多少代码而是它把“工具设计”这件事的门槛拉到了几乎为零。以前你封装一个内部工具得考虑参数解析、补全、帮助文档、异常输出现在这些都不用操心写一份 YAML 就完事。我甚至用它封装过需要多人协作的运维手册把一堆 Markdown 文档中的命令整理到一起改成可执行的 CLI 之后大家肉眼可见地更愿意用了。这个变化让我确信工程师不是不喜欢用命令行而是不喜欢记一堆语境复杂的命令。CLI-Anything 统一了语境自然就有价值。最后分享一个我一直在用的小技巧在tool元信息里加上owner和support_url两个字段生成出来的--help里会自动带上负责人和求助入口。团队里其他同事遇到问题时第一时间能看到找谁这对内部工具的长期维护帮助极大。工具链是好是坏往往不取决于实现而取决于使用者的体验和求助路径是否顺畅。CLI-Anything 的文档里没怎么强调这个细节但我觉得这才是它最让我惊喜的地方之一。
