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

cargo install --git https://github.com/ff4415/aegis.git espctl --locked
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

Release Path

GitHub Releases is the public distribution channel

Prebuilt binaries are meant to ship through GitHub Releases. Until that lands, source install remains the most reliable path.

Public distribution uses Releases

Prebuilt binaries belong on GitHub Releases for clean downloads and version history.

Source install is still the safest path

Until binaries are fully covered, source install remains the most reliable entry.

Remote access stays separate

Public downloads and remote build permissions are different tracks and should stay separate.

Binary asset

espctl-aarch64-apple-darwin.tar.gz / espctl-x86_64-apple-darwin.tar.gz

Choose the Apple Silicon or Intel archive by CPU.

Open Releases Request Remote Build Preview

Grab the binary directly

curl -fL https://esphome.cloud/espctl/espctl-aarch64-apple-darwin.tar.gz \
  | tar xz -C /usr/local/bin espctl

Remote build is still a preview lane. Public downloads and public remote access are not the same thing.

Repo and docs

If you want to inspect the source and the real command surface first, go straight to the aegis repo. This page is here to make agent onboarding, capability boundaries, and release path obvious.

Open aegis repo