CLI Utilities

A catch-all chapter for espctl subcommands and global flags that don’t fit a topic page — version reporting, machine-readable skills introspection, and the cross-cutting --json / --quiet flags.

If you’re looking for per-topic CLI references — espctl build, espctl flash, espctl ide sync, etc. — see the relevant chapter under Tool Reference instead.

Global flags

These two flags work on every subcommand. A third (--skills) works without one and is documented separately below.

--json is parsed as a top-level flag, so every subcommand accepts it without error — but only structured-output commands actually emit JSON on stdout. For build / flash / clean / set-target / login / ide sync / mcp serve / monitor / provision-host without --dry-run, --json only affects the error format (stderr becomes { "error": "..." }); the human progress messages on stdout are unchanged. The commands that produce a JSON payload on success are:

• espctl version, espctl doctor, espctl size, espctl artifacts, espctl ports, espctl probe, espctl probes list, espctl elf (binary, but errors are JSON)
• espctl skills --format json|schema
• espctl catalog --json|--schema
• espctl deposit list --json, espctl deposit verify --json (per the deposit page)

espctl version

Prints the espctl binary version (CARGO_PKG_VERSION).

espctl version

Output

Human mode:

espctl 0.4.2

JSON (--json):

{ "espctl_version": "0.4.2" }

espctl --version vs espctl version

espctl --version (handled automatically by clap) prints the same version string but cannot output JSON. The dedicated version subcommand exists so --json consumers can parse the result.

espctl skills

Prints a machine-readable manifest of every skill the espctl toolchain claims to support — useful when an AI tool or another automation needs to discover what espctl can do without parsing help text.

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

Flag matrix

Manifest contents

The manifest reports skills_spec_version: 1, the tool name (espctl) and binary version, plus 24 skills covering the full lifecycle:

• IDF: idf.select_version, idf.versions
• Project: project.init, project.create, project.create_component
• Build: build.start, build.status, build.cancel, set_target.run
• Artifacts: artifacts.list, artifacts.manifest, logs.tail
• Analysis: size.run, sbom.create, diag.run
• Firmware: firmware.list, firmware.download, flash.run
• Health: doctor.run
• RSHome: rshome.validate, rshome.components.list, rshome.components.add, rshome.pin_map, rshome.codegen.preview

It also exposes global_constraints (no arbitrary commands, allowed roots, network disabled by default, per-target build dirs, artifacts emit a manifest) and the exit_codes map.

Exit codes for skills introspection

(Other CLI-wide codes still apply for I/O errors, but skills-specific errors land on 10.)

Examples

# Default markdown rendering
espctl skills

# Full JSON manifest, suitable for an AI tool's discovery flow
espctl skills --format json

# Machine-readable schema for static validation
espctl skills --format schema

# One specific skill (markdown)
espctl skills --name doctor.run

# One specific skill (JSON)
espctl skills --format json --name build.start

espctl –skills (early exit)

--skills is parsed before clap dispatches to a subcommand. That means espctl --skills works without supplying a subcommand — implicitly equivalent to espctl skills --format md.

Use this when an AI tool’s bootstrap path needs to discover capabilities without first going through clap validation (which would otherwise require a subcommand).

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

--json and --quiet are honored. --skills does not accept any other flags.

espctl catalog

Prints every AegisError code the toolchain can surface, paired with its human-readable message and remediation hint. Useful when an operator (or a log-scraper agent) wants to learn what each [CODE] means without grepping source.

espctl catalog            # markdown (default)
espctl catalog --json     # flat JSON, one record per error
espctl catalog --schema   # JSON Schema for the AegisError wire format

--json and --schema are mutually exclusive. Output goes to stdout in all three modes.

espctl probes

Lists connected debug probes via probe-rs. Used when you have a Cortex-M flash bundle and need to confirm a J-Link / ST-LINK / DAPLink-class probe is reachable before espctl flash or espctl monitor --rtt.

espctl probes list           # table (default)
espctl probes list --json    # structured records suitable for piping

Currently the only subcommand is list. Returns probe vendor, product, serial, vid, pid, and the probe-rs identifier you would pass to --probe on flash / monitor.

espctl update

Checks for and installs a newer version of espctl from the official release CDN (https://esphome.cloud/espctl/).

espctl update           # check and install if newer available
espctl update --check   # check only, don't install
espctl update --force   # force reinstall even if up to date

Flags

How it works

1. Queries https://esphome.cloud/espctl/VERSION to find the latest release version.
2. Compares the release version against the running binary’s compile-time version (espctl --version).
3. Downloads the matching platform asset from the CDN, extracts the binary, atomically replaces the running executable, and verifies the new binary reports the expected version.
4. On failure, the previous binary is restored automatically.

The command is self-contained — no additional dependencies beyond what espctl already links (rustls + reqwest).

espctl provision-host

Provisions the local host so probe-rs can talk to Cortex-M debug probes without root — udev rules on Linux, Zadig hints on Windows; macOS works out of the box.

espctl provision-host --dry-run    # print the plan, do not write
espctl provision-host              # actual install (Phase 3+)

Phase 0 ships only --dry-run. Running without --dry-run today prints a pointer to the dry-run plan and exits 0; real filesystem writes (udev rules, group membership) land in Phase 3.

Exit code reference (CLI-wide)

espctl returns the same set of exit codes regardless of subcommand:

Errors print to stderr in human mode (error: <message>) or as JSON in --json mode ({ "error": "<message>" }). --quiet does not suppress error stderr — the exit code is still meaningful and the message is printed.

Credentials and login

The CLI saves credentials with espctl login to ~/.config/espctl/credentials.json (mode 0600). The full reference is in Plan-only vs Remote Build → Logging in — it covers the --server / --token flags, HTTPS enforcement, and the ESPCTL_ALLOW_INSECURE escape hatch.

See also

• Build Lifecycle — espctl build — remote vs. local, full flag matrix.
• Firmware & Flash — espctl ports, espctl probe, espctl flash, espctl monitor.
• Tool Index (A–Z) — every CLI subcommand, alphabetically.
• Environment Variable Index — CLI-side env vars (ESPCTL_SYSROOT, DEFAULT_IDF_VERSION, etc.).