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.

Flag	Behavior
`--json`	Emit machine-readable JSON to stdout (where the subcommand has a structured output). Errors go to stderr as `{ "error": "<message>" }`.
`--quiet`	Suppress all stdout output. The exit code is the only signal. Wins over `--json` if both are set — the JSON payload is suppressed too.

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.

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

Flag	Default	Notes
`--format`	`md`	One of `md` (markdown), `json` (full `SkillsManifest`), or `schema` (JSON Schema for `SkillsManifest`).
`--name`	—	Filter to a single skill name. Unknown name → exit code 10.

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

Code	Meaning
0	success
10	unknown format or unknown skill name

(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.

Exit code reference (CLI-wide)

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

Code	Meaning	Source
0	success	`EXIT_SUCCESS`
1	runtime / build / I/O error	`BuildFailed`, `Io`, `Other`
2	configuration / input error	`Config`, `InvalidTarget`, `Store`, `Version`, `BuildPlan`
10	unknown skills format or unknown skill name	`espctl skills` only

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.

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.

ESP-IDF MCP — User Manual