CLI-Anything：配置驱动的命令行工具生成器，让脚本管理更高效

CLI-Anything 是我最近一直在维护的一个配置驱动式命令行工具生成器项目名听起来有点狂但思路其实特别朴素把日常重复的运维操作、接口调用、文件整理全部收拢成一条命令。它解决的核心痛点是脚本散落——每个人电脑上大概都有一堆临时 Shell、Python 脚本时间一长连自己都忘了参数怎么写更别说让同事接手。CLI-Anything 把参数定义、执行动作、帮助文档从代码里剥离放进一份 YAML 配置里。于是不需要写主程序只要会写配置就能得到一个带参数校验、自动补全、错误提示的正式 CLI。这套东西最适合三类人经常写临时脚本却老忘参数的系统管理员需要把接口调用收拢给同事用的测试开发以及像我一样反感鼠标点来点去的终端党。下面我会从设计思路、核心机制、实操案例到踩坑记录把它的每个重要环节都讲清楚。1. 项目整体设计与思路拆解1.1 为什么需要“万物皆可CLI”我见过太多团队的工作目录里躺着deploy_tmp.sh、send_report.py、check_api_v2.py每个脚本作者的命名习惯都不同参数风格也完全不一样。真正让人头疼的不是写脚本本身而是过两三个月之后自己都分不清哪个是最终版本哪个是废弃版本。命令行工具的价值在于把“执行动作”收敛到一个统一入口用户只需要记住命令 场景而不需要关心这个动作背后是 Python、Shell 还是 HTTP 请求。这能显著降低记忆负担和出错概率尤其在凌晨处理告警的时候少一个心智负担就少一次事故。CLI-Anything 并不是要把所有软件都强行变成终端程序而是提供一个“中间层”把散落的动作按统一规则组织起来。可以把它理解成终端世界的收纳盒——你不必学每个脚本的内部实现只要通过全局一致的方式去调用即可。这个设计理念决定了后面所有功能上的取舍优先保证简单、一致、可组合而不是追求复杂逻辑的表达能力。1.2 CLI-Anything 的核心架构项目整体分为四个模块配置解析器、命令树构建器、参数运行时、执行引擎。配置解析器负责读取 YAML 并做 schema 校验不合规的配置会直接报错而不是运行到一半才发现问题。命令树构建器把多个命令组织成层级结构支持namespace command --flag这样的调用方式。参数运行时根据配置声明解析用户输入负责类型转换、默认值填充和交互提示。执行引擎则负责把解析好的参数渲染进执行模板然后交给子进程或内置的 HTTP 模块执行。从模块划分上可以直观看出“配置即定义”的思想模块核心职责关键设计点配置解析器读取 YAML、校验结构格式错误必须提前暴露命令树构建器构建命令与帮助索引命令之间互相独立、可复用参数运行时解析参数、类型校验、交互提示与配置声明强一致执行引擎渲染模板、执行脚本/HTTP正确传递退出码和应用超时这四个模块分层很明确执行引擎不关心配置怎么存储参数运行时也不直接拼接命令。这样做的好处等到排查问题时特别明显——参数问题去args声明里找执行问题去看exec配置不会像写面条代码一样两边纠缠不清。1.3 为什么不直接用 Cobra / Click / 纯 Shell很多人会问这些东西用 Bash 函数、Python Click、Go Cobra 不是也能做吗确实能但每个方案都有自己的适用边界。方案优势痛点纯 Shell 脚本随处可用、零依赖参数解析全靠手工帮助信息全无脚本一长容易失控Python Click/Argparse生态成熟、能力全面每次改命令都要改代码非开发同学难以维护Go Cobra二进制分发方便、性能好需要编译环境每次调整都要重新编译发布CLI-Anything配置即命令、上手快复杂逻辑仍需调用外部脚本兜底选择配置驱动是一种折衷。大量的“把若干命令串一下”“把某个接口包一层”“给某个脚本加个正式入口”场景完全不需要写代码。Configuration as Code 对团队协作也很友好非开发岗位的同事看 YAML 比看 Python 轻松得多。如果真遇到非常复杂的逻辑CLI-Anything 也允许script调用任何已存在的脚本保持开放性不硬把逻辑塞进 YAML。2. 核心机制解析与关键配置要点2.1 从一份 YAML 认识命令定义要理解 CLI-Anything最好的方式就是直接看配置。以下是一份最简单的ops.yamlname: ops description: 日常运维工具箱 version: 1.0.0 commands: - name: disk description: 查看磁盘占用 args: - name: path type: string default: / help: 要查看的分区路径 exec: script: df -h {{path}}顶层name是命令前缀也可以理解成命令空间。commands是命令列表每个命令必须有name和description。args里声明参数注意参数名不带横线CLI 调用时会自动映射成--pathexec.script中的{{path}}是模板占位符运行时会被实际参数值替换。写完配置后直接运行ca run ops.yaml disk ca run ops.yaml disk --path /data第一条命令会把默认值/传给模板实际执行df -h /第二条命令则执行df -h /data。从这段配置可以看到一个关键机制CLI-Anything 本身不关心命令业务它只负责把“用户输入”安全、可预期地变成“实际执行动作”。2.2 参数类型与校验规则参数声明不是摆设CLI-Anything 会按照类型对输入做严格校验。目前内置的类型包括类型说明配置示例string字符串name: appint整数port: 8080float浮点数ratio: 0.4boolean布尔开关verbose: truechoice枚举值level: infopath路径自动规范化log: /var/logsecret敏感信息交互输入不回显token: xxxx如果用户传入--port abc运行时会直接报错“参数 port 需要 int 类型当前是 abc”而不是等脚本执行到一半才暴露问题。choice类型会列出所有合法值比如--level warning如果不在[debug, info, warning, error]内会提示可选项。required: true且没有默认值时未传参就会直接以非零退出码结束如果同时配置了prompt: true则会进入交互式输入secret类型输入时不回显适合处理 API Token、密码这类信息。2.3 多命令编排与输出格式化单命令只是基础实际运维场景中更常见的是“巡检”这一类组合动作。CLI-Anything 提供steps编排字段commands: - name: full description: 执行完整巡检 steps: - command: disk - command: mem - script: echo system uptime uptime这段配置的意思是先执行已定义的disk命令再执行mem命令最后执行一段临时 script。使用steps的好处是复用已有的命令定义不需要在每个命令里重复写df、free这些底层指令。steps中command也可以传参格式如下steps: - command: disk args: path: /opt输出方面CLI-Anything 默认透出子进程的 stdout同时支持声明式结果格式。比如在exec中配置output: json内置的 JSON 格式化器会自动把命令输出按 key 排序并美化--format json全局参数也可以临时覆盖输出格式。这一设计的目的很功利便于把命令结果直接喂给监控系统或 CI 日志不需要再单独写文本解析逻辑。2.4 环境变量、别名与全局参数实际使用中很多脚本离不开环境变量。CLI-Anything 允许在配置顶层声明环境变量env: APP_ENV: production NOTIFY_URL: https://hooks.example.com/callback这些变量会注入到执行子进程的环境里脚本里直接echo $APP_ENV就能取到。更常用的是配合 HTTP 执行器比如请求头里写Authorization: Bearer ${WEATHER_TOKEN}这个变量可以从当前 Shell 环境继承也可以写在配置文件中。别名和全局参数能显著提升日常体验aliases: d: disk full-check: full global_args: - name: timeout type: int default: 30 help: 内置执行超时时间配置了d别名之后ca run ops.yaml d --path /data和完整写法等价。global_args里的参数是所有命令共享的比如内置的执行超时--timeout用户不传默认 30 秒传了则覆盖默认值。这些小功能单独拎出来都不复杂但组合在一起才让工具显得贴心。3. 实操从零构建一个服务器巡检命令3.1 极简起步一条 disk 命令先创建目录和工作文件mkdir -p ~/tools touch ~/tools/ops.yaml把下面内容写进ops.yamlname: ops description: 日常运维工具箱 version: 1.0.0 commands: - name: disk description: 查看磁盘占用可指定分区 args: - name: path type: string default: / help: 要查看的挂载点路径 exec: script: df -h {{path}}保存后运行ca run ops.yaml disk ca run ops.yaml disk --path /data第一次运行会看到df -h /的输出。如果加上--debug参数CLI-Anything 会在执行前打印模板渲染后的真实命令ca run ops.yaml disk --path /data --debug [debug] execute script: df -h /data Filesystem Size Used Avail Use% Mounted on /dev/vda1 99G 60G 34G 64% /data--debug是我每次排错第一个打开的参数。它能确认模板替换是否符合预期避免出现“我以为传的是 /data实际脚本里还是 /”这种低级问题。3.2 组合巡检流程把多条命令串起来单条命令不能满足真实巡检需求。我把ops.yaml扩展成三条命令加入内存和完整巡检name: ops description: 日常运维工具箱 version: 1.0.0 commands: - name: disk description: 查看磁盘占用 args: - name: path type: string default: / help: 要查看的挂载点 exec: script: df -h {{path}} - name: mem description: 查看内存占用 exec: script: free -m - name: full description: 执行磁盘、内存、负载完整巡检 steps: - command: disk - command: mem - script: echo system uptime uptime运行完整巡检ca run ops.yaml full它会依次输出磁盘、内存、uptime 三部分内容。这种组合方式特别适合值班场景一条命令代替三五个检查动作误操作概率也大幅下降。如果在steps里引用了不存在的命令CLI-Anything 会定位到具体的步骤序号比如“步骤 3 引用了命令 unknown请检查配置”比 Shell 脚本报一个莫名其妙的命令找不到要友好得多。3.3 参数传递、默认值与交互式输入巡检命令通常需要一个阈值参数比如磁盘使用率超过 80% 时给出告警。我在 disk 命令里加一个warning参数- name: disk description: 查看磁盘占用 args: - name: path type: string default: / - name: warning type: int default: 80 help: 告警阈值 exec: script: | USE$(df -H {{path}} | awk NR2 {print $5} | tr -d %) if [ $USE -gt {{warning}} ]; then echo WARNING: disk usage is {{warning}}% exit 1 else echo OK: disk usage is $USE% fi这里用了 YAML 的|多行语法script 可以写成完整 Shell 脚本。如果用户不传--warning默认用 80想临时改成 90 就运行ca run ops.yaml disk --path /data --warning 90。对于必须手动输入的敏感参数可以启用交互式输入args: - name: token type: secret required: true prompt: true help: 调用内部接口的 token运行后 CLI 会提示“请输入 token:”输入内容不回显。这个能力很重要否则每次都在命令里写明文 Token会被history记录得清清楚楚存在不小的安全隐患。4. 实操把外部API包装成命令行工具4.1 定义 HTTP 命令天气查询实例CLI-Anything 不只是能执行 Shell 脚本内置的 HTTP 执行器可以把任意 HTTP 接口包装成命令。这里用api.example.com作为占位地址演示name: api description: 常用接口查询工具 commands: - name: weather description: 查询城市天气 args: - name: city type: string required: true help: 城市拼音比如 beijing exec: type: http method: GET url: https://api.example.com/v1/weather?city{{city}} headers: Authorization: Bearer ${WEATHER_TOKEN} output: json运行export WEATHER_TOKENyour_token_here ca run api.yaml weather --city beijing由于执行器是 HTTP 而不是 Shell{{city}}会被自动做 URL 编码不需要担心中文或特殊字符破坏请求地址。WEATHER_TOKEN从当前环境变量读取读取失败时会有明确的报错提示而不是把空字符串发到对方服务。4.2 处理返回结果与错误信息HTTP 请求不可能永远成功。CLI-Anything 对非 2xx 状态码的处理逻辑是把响应体输出到 stderr并以非零退出码结束。这样在 CI 脚本里可以自然失败不会被管道掩盖。如果接口有自己的业务码比如返回{code: 500, msg: error}但 HTTP 状态码是 200这属于业务异常。可以在exec里配置断言exec: type: http method: GET url: https://api.example.com/v1/weather?city{{city}} asserts: - path: $.code equals: 200断言失败时CLI-Anything 会打印实际值和期望值assert failed: $.code 200, actual value is 500这一层防护非常实用能够提前拦住“接口返回了错误数据但进程退出码为 0”的隐蔽问题。4.3 把命令交给同事帮助信息与自动补全自己用的工具再顺手最终也要交给别人。CLI-Anything 一个很大的优势是帮助信息自动生成。运行ca run api.yaml weather --help会输出类似下面的内容api weather - 查询城市天气 用法: ca run api.yaml weather [--city string] 参数: --city string 城市拼音比如 beijing (必填)同事不需要打开配置文件就能知道这个命令怎么用。除此之外还能生成 Shell 补全脚本ca completion api.yaml ~/.bash_completion.d/api source ~/.bash_completion.d/api之后输入ca run api.yaml weather --c再按 Tab就能自动补全--city。如果city字段配了choices连可选值都能列出来。更友好的是如果不想让同事安装 CLI-Anything可以用 build 子命令生成独立脚本ca build api.yaml -o /usr/local/bin/weather-cli生成的脚本不依赖 CLI-Anything适合分发到没有 Python 环境的机器上。不过对于内部工具我建议优先直接共享 YAML 配置文件因为后续修改命令不再需要重新分发二进制。5. 常见问题与排查技巧实录5.1 YAML 配置解析失败怎么办CLI-Anything 对配置格式是强校验的YAML 解析失败会直接终止。最常见的错误是缩进不一致比如混用 tab 和空格或者在列表项下面少缩进了一个层级。建议所有配置文件统一使用两个空格缩进并配置编辑器把 tab 自动展开成空格。多行脚本时也容易踩坑。正确写法是用|exec: script: | echo start sleep 1 echo done如果写成普通字符串换行可能丢失脚本会变成一行。另一个冷知识是 YAML 里:后面必须有空格中文冒号也不会被识别。遇到解析报错时第一反应不是检查语法而是把配置复制到在线 YAML 校验工具里先确认 YAML 本身合法再排查 CLI-Anything 的字段语义。5.2 参数没有按预期传递或校验不通过参数不生效通常有三类原因。第一种是调用时忘了--前缀ca run ops.yaml disk /data不会把/data当成path参数CLI-Anything 只认--path形式。第二种是大小写不匹配YAML 里声明name: path运行--Path /data是无效的。第三种是布尔参数传值方式错误比如--verbose false不会把 verbose 设为 false而是把它整体当成 true正确写法是--verbosefalse。还有一个容易被忽略的问题截图或文章里的单引号、双引号复制到终端时可能变成中文引号。这类问题肉眼很难发现但报错信息里通常能看出端倪。遇到参数相关的问题先开--debug看模板渲染结果看最终传给脚本的参数值到底是什么别猜。5.3 命令执行报错但看不到原因Shell 命令执行失败时CLI-Anything 默认会把 stderr 原样输出。如果看不到报错第一检查退出码echo $?。第二打开--debug看渲染后的实际命令。第三如果脚本内部先失败但后续命令又成功导致整体退出码为 0这是 Shell 脚本常见陷阱需要在脚本开头加set -eexec: script: | set -e df -h {{path}} echo doneset -e会在任意一条命令失败时立即退出脚本退出码就是失败命令的退出码。对于 HTTP 命令--log-level trace可以打印完整请求和响应信息但注意这可能包含 Token 等敏感字段排错后要关掉并且不要在生产环境长期开启。5.4 跨平台执行与安全隐患配置驱动工具最容易忽略的就是跨平台问题。df、free这些命令在 Linux 上没问题但 macOS 的df参数略有差异Windows 又完全是另一套逻辑。项目不可能保证所有命令跨平台只需要在配置里明确适用范围并在帮助信息里写明“仅支持 Linux”。更需要注意安全。使用exec.script时参数值会被渲染进 Shell 命令存在注入风险。比如path传入; rm -rf /就会发生不可预期的事。建议优先使用数组形式exec: command: [df, -h, {{path}}]数组形式不经过 Shell 解释参数按原样传给子进程不存在注入问题。对于choice类型参数由于值被枚举限制风险会进一步降低。凡是涉及 Secret 的配置不要明文写在 YAML 里统一从环境变量读取。下面把几个高频问题整理成速查表问题快速排查推荐做法YAML 解析报错检查缩进、tab、中文符号统一两空格缩进多行用 参数不生效检查--前缀、大小写、类型用--help和--debug验证脚本失败但命令退出码为 0检查是否缺少set -e脚本开头加set -e特殊字符导致命令被篡改检查是否使用script拼接改用command数组形式6. 后续扩展方向与个人体会6.1 还能继续折腾的玩法CLI-Anything 的配置驱动模型决定了它很容易继续扩展。目前常见的玩法有三种一是用ca build把常用命令打包成独立二进制塞进 Docker 镜像或 CI 运行环境二是通过执行前后钩子把运行结果推送到内部 IM 机器人实现命令结束通知三是把多个 YAML 配置文件放到统一目录团队共享一套命令入口后续只需要同步一个目录。如果你有兴趣还可以给配置增加自定义插件把项目内部特定的解析逻辑封装成 Python 类。但在加功能之前一定要克制CLI-Anything 最大的优势是轻量一旦配置里出现太多自定义扩展就慢慢变成了另一个编程框架反而丢掉了“非开发同学也能维护”这个核心价值。6.2 用了大半年之后的真实感受我的个人经验是刚开始不要想着把整套工作流一次性搬进去从一两条最频繁的命令开始就好。我最早只配置了disk和log两条命令用了两周后才逐渐加巡检、接口查询、告警通知。这个节奏让配置文件始终处于可控范围不会一上来就因为过度设计而放弃。另一个体会是帮助信息会被严重低估。以前写临时脚本从来不写文档三个月后自己都看不懂现在每条命令的description都是强制字段相当于顺手补了文档。最后一点配置驱动的工具不是银弹复杂业务逻辑还是应该写在正经语言里CLI-Anything 适合做那个“入口”而不是所有逻辑的宿主。把它定位成一层薄薄的胶水你会发现它真的能让日常操作变得顺手很多。