Tool Reference — Overview

espctl gives your AI assistant 40 tools — 27 unique MCP tools in six groups, 9 RSHome tools for smart-home device configuration, and 4 alias names for backwards compatibility — plus 15 CLI subcommands for hand-driven workflows (see IDE Integration and CLI Utilities). This page is the map; each section below links to the full reference for one group.

At a glance

Two name styles

You’ll see two naming styles:

• Dotted (build.cancel, build.status, project.init, firmware.list) — newer tools.
• Underscored (idf_select_version, list_artifacts, generate_build_plan, get_clean_plan, parse_build_errors, parse_size_report, set_target, store_versions, validate_config) — older tools, kept around so existing setups don’t break.

Four tools have alias names: build ⇄ build.start, doctor ⇄ doctor.run, idf_select_version ⇄ idf.select_version, and list_artifacts ⇄ artifacts.list. Each alias points at the same implementation — pick whichever your AI tool surfaces and stick with it.

Decision tree: which tool do I want?

I want to ...                                           →  Use ...
─────────────────────────────────────────────────────────────────────
... start a fresh ESP-IDF project                       →  project.init
... create a project from a template                    →  project.create
... add a component to an existing project              →  project.create_component
... change the chip on an existing project              →  set_target
... run set-target on the build machine                 →  set_target.run
... check my .espctl.toml is valid                      →  validate_config
... pick which IDF version a build will use             →  idf_select_version
... see what IDF versions the build server has          →  store_versions
... see IDF version details (path, commit, default)     →  idf.versions
... check everything is set up right                    →  doctor
... compile firmware                                    →  build
... see if my running build is done                     →  build.status
... stop a running build                                →  build.cancel
... see what a build WOULD do (without running it)      →  generate_build_plan
... see what a clean would delete                       →  get_clean_plan
... read build log lines                                →  logs.tail
... see what files the build produced                   →  list_artifacts
... read the official manifest.json                     →  artifacts.manifest
... turn raw compiler errors into something readable    →  parse_build_errors
... read flash/RAM usage from the build                 →  parse_size_report
... get detailed size breakdown (components/files)      →  size.run
... generate a software bill of materials               →  sbom.create
... run diagnostics on a completed build                →  diag.run
... list builds with downloadable firmware              →  firmware.list
... get firmware download metadata                      →  firmware.download
... flash firmware to a device over USB                 →  flash.run
... capture serial output from a flashed device         →  monitor.run

How tools get called

Every tool takes a name and a JSON arguments object. The exact way you trigger them depends on your AI tool — most assistants pick the right tool and arguments automatically based on what you ask, but you can always be explicit:

Call the build tool with target esp32s3 and profile release.

If you want to see what arguments a tool accepts before calling it, ask:

Show me the schema for the build tool.

Most AI tools will dump the input/output shape.

Things to know about all tools

• task_id — Build tools return a task_id right away and finish in the background. Your assistant checks build.status (or reads build://log/{task_id}) to follow along. To stop early, use build.cancel.
• Status values — pending, running, succeeded, failed, canceled.
• Errors — When something goes wrong inside the build itself (compiler error, link failure), the tool succeeds — the failure shows up in build.status and the log. Tool errors are reserved for “the tool itself broke”.
• Paths — All paths come from the build server’s filesystem. They look like /work/... because the build server runs in a sandbox; they don’t match anything on your computer.

Ready? Let’s start with the most important group: Build Lifecycle.