CLI 实用工具

收纳那些不属于某个主题页的 espctl 子命令和全局标志 —— 版本信息、 机器可读的 skills 清单,以及横跨各处的 --json / --quiet。

如果你想找按主题分的 CLI 参考(比如 espctl build、espctl flash、 espctl ide sync 等),请去 工具参考 下对应的章节。

全局标志

下列两个标志对所有子命令都有效。第三个(--skills)不需要子命令, 单独在下面说明。

--json 是 top-level 标志,所有子命令都接受不报错 —— 但只有 结构化输出的命令真的会在 stdout 吐 JSON。对 build / flash / clean / set-target / login / ide sync / mcp serve / monitor / provision-host(不带 --dry-run)这些命令,--json 只改错误格式 (stderr 变成 { "error": "..." }),stdout 上的人类进度信息没变。 真的会产出 JSON 负载的命令是:

• espctl version、espctl doctor、espctl size、 espctl artifacts、espctl ports、espctl probe、 espctl probes list、espctl elf(二进制下载,错误才是 JSON)
• espctl skills --format json|schema
• espctl catalog --json|--schema
• espctl deposit list --json、espctl deposit verify --json (详见 deposit 页)

espctl version

打印 espctl 二进制版本(CARGO_PKG_VERSION)。

espctl version

输出

Human 模式:

espctl 0.4.2

JSON(--json):

{ "espctl_version": "0.4.2" }

espctl --version vs espctl version

espctl --version 由 clap 自动处理,打印同样的版本字符串,但不能 切到 JSON 输出。专门的 version 子命令存在的目的就是给 --json 消费者用。

espctl skills

打印 espctl 工具链声明支持的每一个 skill 的机器可读清单 —— 当 AI 工具或其它自动化系统需要发现 espctl 能做什么、又不想解析帮助文档 时,就走这里。

espctl skills [--format md|json|schema] [--name <skill>]

标志矩阵

清单内容

清单字段:skills_spec_version: 1、工具名(espctl)、二进制版本, 以及覆盖完整生命周期的 24 个 skill:

• IDF:idf.select_version、idf.versions
• 项目:project.init、project.create、project.create_component
• 构建:build.start、build.status、build.cancel、set_target.run
• 产物:artifacts.list、artifacts.manifest、logs.tail
• 分析:size.run、sbom.create、diag.run
• 固件:firmware.list、firmware.download、flash.run
• 健康检查:doctor.run
• RSHome:rshome.validate、rshome.components.list、 rshome.components.add、rshome.pin_map、rshome.codegen.preview

清单还包含 global_constraints(不允许任意命令、允许的根目录、默认 网络禁用、按 target 分构建目录、产物自带 manifest)和 exit_codes 映射。

Skills 自身的退出码

(其它 CLI 通用退出码也仍然适用,例如 I/O 错误;但 skills 自身的 错误落在 10。)

示例

# 默认 markdown 输出
espctl skills

# 完整 JSON 清单,适合 AI 工具的工具发现流程
espctl skills --format json

# JSON Schema,做静态校验
espctl skills --format schema

# 只看一个 skill(markdown)
espctl skills --name doctor.run

# 只看一个 skill(JSON)
espctl skills --format json --name build.start

espctl –skills(提前退出)

--skills 在 clap 分发到子命令之前就被解析。也就是说 espctl --skills 不需要传子命令也能跑 —— 等价于 espctl skills --format md。

适合 AI 工具启动时快速发现能力,不需要先经过 clap 的子命令 强制校验。

espctl --skills
espctl --skills --json
espctl --skills --quiet; echo "rc=$?"

--json 和 --quiet 都生效。--skills 不接受其它任何标志。

espctl catalog

打印工具链能抛出的全部 AegisError 错误码,配人类可读的消息和 整改建议。给运维(或日志抓取 agent)用,免得想知道某个 [CODE] 是什么意思还得去翻源码。

espctl catalog            # markdown(默认)
espctl catalog --json     # 扁平 JSON,一条 record 对应一个错误
espctl catalog --schema   # AegisError 线格式的 JSON Schema

--json 与 --schema 互斥。三种模式都打 stdout。

espctl probes

通过 probe-rs 列出当前连接的调试探头。在烧 Cortex-M flash bundle 前确认 J-Link / ST-LINK / DAPLink 类探头可达时常用,后续接 espctl flash 或 espctl monitor --rtt。

espctl probes list           # 表格(默认)
espctl probes list --json    # 结构化记录,适合管道

目前只支持 list 子命令。返回 vendor、product、serial、vid、 pid,以及给 flash / monitor 的 --probe 用的 probe-rs 标识。

espctl provision-host

把本地主机配好,让 probe-rs 不用 root 就能跟 Cortex-M 调试探头 通信 —— Linux 上是 udev 规则、Windows 上是 Zadig 提示;macOS 开箱即用。

espctl provision-host --dry-run    # 打印计划,不写盘
espctl provision-host              # 实际安装(Phase 3+)

Phase 0 只实现 --dry-run。当前不带 --dry-run 直接跑,只会打印 指向 dry-run 计划的提示并以 0 退出;真正的文件写入(udev 规则、 用户组管理)留到 Phase 3 落。

CLI 通用退出码

espctl 在所有子命令下都遵循同一套退出码:

错误在 human 模式下以 error: <message> 打到 stderr;--json 模式 下以 { "error": "<message>" } 打。--quiet 不会抑制 stderr 错误 —— 退出码仍然有效,消息也会打出来。

凭据与登录

CLI 通过 espctl login 把凭据保存到 ~/.config/espctl/credentials.json(权限 0600)。完整参考见 仅计划模式 vs 远程构建 → 登录 —— 那里讲了 --server / --token 标志、HTTPS 强制要求,以及 ESPCTL_ALLOW_INSECURE 这个开发用的逃生口。

另见

• 构建生命周期 — espctl build —— 远程 vs 本地、完整标志矩阵。
• 固件与烧录 —— espctl ports、espctl probe、 espctl flash、espctl monitor。
• 工具索引(A-Z) —— 字母顺序的所有 CLI 子命令。
• 环境变量索引 —— CLI 侧的环境变量(ESPCTL_SYSROOT、DEFAULT_IDF_VERSION 等)。