Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CLI 实用工具

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

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

全局标志

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

标志行为
--json当子命令有结构化输出时,把它当 JSON 打到 stdout。错误以 { "error": "<message>" } 打到 stderr。
--quiet抑制全部 stdout 输出。退出码是唯一信号。和 --json 同时设置时,--quiet 优先 —— JSON 也被抑制。

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>]

标志矩阵

标志默认说明
--formatmdmd(markdown)、json(完整 SkillsManifest)或 schema(SkillsManifest 的 JSON Schema)三选一。
--name—过滤到单个 skill 名。未知名字 → 退出码 10。

清单内容

清单字段: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 自身的退出码

退出码含义
0成功
10未知 format 或未知 skill 名

(其它 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 不接受其它任何标志。

CLI 通用退出码

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

退出码含义来源
0成功EXIT_SUCCESS
1运行时 / 构建 / I/O 错误BuildFailed、Io、Other
2配置 / 输入错误Config、InvalidTarget、Store、Version、BuildPlan
10未知 skills format 或未知 skill 名仅 espctl skills

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

凭据与登录

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

另见