Install & Login

Install espctlin three commands

From zero to working: one command installs the CLI, one logs in with your preview token, one verifies the environment. Everything after is your agent driving ESP32 builds.

Read the manual

Step 01

Install the CLI

Detects your OS, drops espctl into your PATH. macOS and Linux share the same script.

~ — install

$curl -fsSL https://esphome.cloud/espctl/install.sh | sh

Step 02

Log in with your preview token

Saves to ~/.config/espctl/credentials.json. espctl build picks it up automatically.

~ — auth

$espctl login --token <your-preview-token>

Step 03

Run doctor before anything else

doctor surfaces env, project config, and login status in one pass.

~/project — healthcheck

$espctl doctor[ok] default-idf-version: DEFAULT_IDF_VERSION=v5.3.1[ok] project-config: .espctl.toml is valid[ok] login: logged in to https://esphome.cloudAll checks passed.

Choose Your Agent

Wire espctl into your agent

Each client gets four things: install, MCP config, a copy-ready prompt, and honest capability boundaries.

Choose the client first

Codex, Claude Code, and OpenCode share one capability boundary but keep distinct entry paths.

Copy from one surface

Install commands, MCP config, and starter prompts live in the same operating zone.

Separate today from preview

Available capabilities and preview-only paths stay split so users do not have to infer risk.

Terminal native

Codex

Install + first command

curl -fsSL https://esphome.cloud/espctl/install.sh | sh
espctl doctor

Codex MCP config

[mcp_servers.espctl]
command = "espctl"
args = ["mcp", "serve"]
cwd = "/path/to/your/esp-idf/project"

[mcp_servers.espctl.env]
CONTROL_BASE_URL = "https://esphome.cloud"
MCP_AUTH_SECRET = "<preview-token>"

Starter prompt

Use espctl to initialize an ESP32-S3 project, pin ESP-IDF v5.3.1, run doctor, then prepare a remote build. If preview access is not configured, stop at the next concrete command I should run.

Current status

What works today

MCP server and skills manifest are available now
doctor, ports, flash, and monitor are available now

Preview lane

Remote build still requires a preview token

Capability Split

Keep today and preview cleanly separated

The page has to stay honest. What works today should be stated plainly, and preview features should stay labeled as preview.

Today stays on the left

Skills, doctor, ports, flash, and monitor remain the stable operating surface.

Preview stays on the right

Remote build still needs preview access and should not blur into the public baseline.

What works today

Expose skills to agents with `espctl mcp serve`
Return machine-readable capabilities with `espctl skills --format json`
Check project and environment with `espctl doctor`
Use `espctl ports`, `flash`, and `monitor` for device handoff

Preview lane

`espctl build` sends to a remote agent by default
Stream logs and build progress back into the client
Receive firmware at completion and continue into flashing