ESP-IDF Store

Three tools let you ask the build server which ESP-IDF versions and tools it has, and check that everything is healthy.

The “store” lives on the build server, not on your computer. You never have to install ESP-IDF locally — these tools just let you peek at what the build server has available so you can pick a version to pin.

store_versions

Returns the list of ESP-IDF versions the build server has available.

Input: None.

Returns:

{
  "store_root": "<store-root>",
  "versions": [
    {
      "version": "v5.3.1",
      "path": "<store-root>/idf/v5.3.1",
      "default": true,
      "tools": ["xtensa-esp32s3-elf", "riscv32-esp-elf", "..."]
    },
    {
      "version": "v5.2.2",
      "path": "<store-root>/idf/v5.2.2",
      "default": false,
      "tools": ["..."]
    }
  ]
}

The version flagged default: true is the one a build will use when nothing else is pinned. To pin a different version on a project, use idf_select_version or set it in .espctl.toml.

No side effects. Safe to call any time.

idf.versions

Like store_versions, but returns more detail per version — the filesystem path, commit hash, and which one is the default.

Input: None.

Returns:

{
  "versions": [
    {
      "version": "v5.3.1",
      "idf_path": "<store-root>/idf/v5.3.1",
      "commit_hash": "abc123...",
      "default": true
    }
  ]
}

The default flag marks the version the build server falls back to when a request does not pin one.

No side effects. Safe to call any time.

doctor / doctor.run

The most important tool when something isn’t working. doctor checks:

1. The build server is reachable — can espctl reach the URL you gave it?
2. Your access key works — does the server accept it?
3. Available IDF versions — what does the build server have?
4. Your project settings — does .espctl.toml parse? Is target valid? Is idf_version something the build server has?

Input: None.

Returns:

{
  "status": "healthy",
  "checks": [
    { "name": "control_plane", "status": "ok", "detail": "https://esphome.cloud/health 200 OK" },
    { "name": "auth", "status": "ok", "detail": "access key accepted" },
    { "name": "store_manifest", "status": "ok", "detail": "3 IDF versions available" },
    { "name": "default_version", "status": "ok", "detail": "v5.3.1" },
    { "name": "project_config", "status": "ok", "detail": ".espctl.toml valid, target=esp32s3" }
  ],
  "warnings": [],
  "errors": []
}

On failure, individual checks downgrade to warning or error:

{
  "status": "unhealthy",
  "checks": [
    { "name": "control_plane", "status": "error", "detail": "ECONNREFUSED https://esphome.cloud" }
  ],
  "errors": [
    {
      "name": "control_plane",
      "message": "Cannot reach the build server. Builds will run in plan-only mode."
    }
  ]
}

Run doctor first when troubleshooting any issue. It catches most setup mistakes in one shot.

See also

• idf_select_version — pick which version a specific build uses.
• Prerequisites — what you need to install on your computer (hint: very little).
• Troubleshooting — what to do when doctor reports errors.