工具命令行界面：用好这三大块，你就能跟它“对话”了

说实话，刚开始用命令行工具的时候，我也觉得黑乎乎的窗口有点吓人。

但用过几次你就会发现，这恰恰是最直接、最高效的方式。效率高在哪儿？不需要鼠标点来点去，一条命令下去，结果就出来了。

常用命令速览——先记住这几个“高频词”

我习惯把命令分成三类：检查类、执行类、辅助类。下面这张表格是我项目中每天都在用的核心命令，你把它贴在手边，基本就够了。

参数类型与使用要领——你真的搞懂这些“选项”了吗？

光知道命令名还不够，参数用不对，什么也干不了。你想想看，一个命令后面跟着的各种“短线+字母”，到底代表什么？

我总结了一下，参数分成这么几种：

• 布尔参数：就是开或关。比如 --verbose 表示输出更多日志，--dry-run 表示“模拟运行，不改代码”（这个我在项目中用过无数次，特别好用）。
• 键值参数：需要你给一个具体的值。--target-dir ./out、--output-format json 都算。注意了，有些工具用空格分隔，有些用等号，建议仔细看帮助系统。
• 短参数与长参数：短参数就是 -v、-o，方便敲键盘；长参数是 --verbose、--output，写在脚本里更好读。我个人建议：在命令行里用短的，在脚本或CI里用长的。
• 路径参数：直接给一个文件或目录路径。我踩过最大的坑就是：路径里带空格，又没有加引号。比如 --config /my files/config.json，工具会认为这是两个参数。所以，路径带空格时一定要加双引号。

内置帮助系统——命令行工具的“说明书”

你可能会问：“这么多参数，我怎么记得住？”

其实不用记。好工具一定有一个好的帮助系统。你看，几乎所有成熟的命令行工具都会提供这些“救命”选项：

• --help 或 -h：最基础的帮助，列出所有命令和选项。
• sdk-tool help [子命令]：查看某个子命令的详细帮助。
• sdk-tool man：打开完整的用户手册（像Linux的man一样）。
• sdk-tool examples：直接看示例。我个人最喜欢这个，因为“一看例子就懂了”。

嗯，这里要注意：帮助系统本身也是有层级的。从上往下看，能看到全局用法；再往下，能深入到子命令。

举个例子，你输入 sdk-tool migrate --help，它不会只告诉你“这是迁移命令”，而是会列出：

用法:
  sdk-tool migrate [选项]

常用选项:
  -t, --target-version <版本>   必需。如 4.0.0
  -s, --source-dir <路径>      代码目录（默认当前目录）
  --dry-run                     只看改动预览，不实际修改文件
  --skip-deps-check             跳过依赖检查（不推荐）
  --output-format <格式>       json / yaml / text

看到了吗？这比你看任何第三方教程都准确。我给团队的建议一直是：遇到问题，先跑 --help。

SVG框架图：命令行工具的核心逻辑

下面这张图，是我自己梳理的“与工具打交道”的流程。你看明白它，命令行这块基本就通了。

说白了，整个交互逻辑就是：你给工具一个命令和参数，它要么告诉你“怎么用”（帮助系统），要么“开始干活”（执行命令）。

避坑指南：我经历过的“参数灾难”

我觉得有些坑，只有自己踩过才会长记性。但既然我能告诉你，你就不用再踩了。

1. 参数顺序问题：很多工具其实不要求参数顺序，但有些工具有“必选参数”和“可选参数”之分，而且必选参数必须放在前面。我的做法：先写命令，再写必选参数，最后写可选参数。这样不容易出错。
2. 配置文件与环境变量：有些参数我是通过 --config 指定的，但如果环境变量 SDK_TOOL_VERBOSE=1 也存在，哪个优先级高？我遇到过的规则是：显式参数 > 环境变量 > 配置文件默认值。当然，最好去帮助文档里确认一下。
3. 输出格式与重定向：如果你需要把迁移报告保存下来，可以用 --output-format json > report.json。但要注意：如果工具本身的日志输出也到了 stdout，你可能会得到一个“日志+报告”的混合文件。这时候要用 2>/dev/null 把错误或日志信息重定向掉。

# 检查项目配置，输出详细日志
sdk-tool check \
  --target-dir ./output \
  --verbose \
  --output-format json > check-result.json