IDE Integration

espctl ide configures local clangd-based IntelliSense from cloud builds — without requiring a local ESP-IDF install. It pulls compile_commands.json, rewrites sandbox paths to a local sysroot, and writes .vscode/settings.json so the clangd extension can do go-to-definition and inline diagnostics out of the box.

Status note: the HTTP download path is currently a placeholder. espctl ide sync reads from a cached compile_commands_raw.json in your local sysroot — typically populated by an earlier successful sync or a local agent build. Future versions will fetch over HTTPS directly. See Limitations below.

Sub-commands at a glance

Sub-command	What it does
`espctl ide sync`	Pull `compile_commands.json`, rewrite paths into a local sysroot, write `.vscode/settings.json` for clangd.

espctl ide sync

espctl ide sync [--idf-version <ver>] \
                [--server <url>] \
                [--sysroot <dir>] \
                [--project <dir>] \
                [--job-id <id>]

Flag matrix

Flag	Default	Notes
`--idf-version`	`.idf-version` → `[idf_version]` in `.espctl.toml` → `DEFAULT_IDF_VERSION` env	Mandatory by transitive resolution. If none of those is set, the command exits with `no IDF version found`.
`--server`	`ESPCTL_SERVER` env → saved login server	Where to fetch `compile_commands_raw.json` from (HTTP path is a placeholder — see Limitations).
`--sysroot`	`ESPCTL_SYSROOT` env → `~/.espctl/sysroot`	Local sysroot base (not the per-version directory).
`--project`	current directory	Project root — where `compile_commands.json` and `.vscode/settings.json` are written.
`--job-id`	last build (reserved)	Currently unused; reserved for explicit build pin.

What it writes

espctl ide sync always writes <project>/.vscode/settings.json. If a cached compile_commands_raw.json is present in the per-version sysroot, it also writes <project>/compile_commands.json after path rewriting.

`<project>/.vscode/settings.json`

The file is written with merge semantics — your existing keys are preserved, only the espctl-managed keys are added or updated:

{
  "clangd.path": "clangd",
  "clangd.arguments": [
    "--background-index",
    "--clang-tidy",
    "--query-driver=<sysroot>/tools/bin/xtensa-esp*-elf-*",
    "--header-insertion=iwyu"
  ],
  "C_Cpp.intelliSenseEngine": "disabled",
  "[c]":   { "editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd" },
  "[cpp]": { "editor.defaultFormatter": "llvm-vs-code-extensions.vscode-clangd" },
  "espctl.ideSyncSysroot":    "<sysroot>/<idf-version>",
  "espctl.ideSyncIdfVersion": "<idf-version>"
}

The espctl.ideSync* keys are provenance markers — they tell future runs (and you) what version this .vscode was generated against.

`<project>/compile_commands.json`

Sandbox paths in the upstream compile_commands_raw.json (e.g. /workspace/main/main.c) are rewritten to the local sysroot path (<sysroot>/<idf-version>/main/main.c) so clangd can find headers and toolchain binaries. The rewrite is done by espctl_core::compile_commands::CompileCommandsRewriter::for_idf_sysroot.

IDE setup checklist

Install the clangd extension in VS Code.
Run a successful build with espctl build so the build’s compile_commands_raw.json is cached locally.
Run espctl ide sync (optionally with --idf-version vX.Y.Z).
Reopen the workspace in VS Code. clangd will pick up the new compile_commands.json and start indexing.

Limitations

HTTP download is a placeholder. Today, ide sync reads from the cached compile_commands_raw.json written by a local agent build (or a previous successful sync). If neither exists, the command warns No compile_commands.json found; run a build first. but still writes .vscode/settings.json.
--job-id is reserved but currently unused — the command always reads from the cached file.

Examples

# Default — uses .idf-version, current dir, ~/.espctl/sysroot
espctl ide sync

# Pin a specific IDF version
espctl ide sync --idf-version v5.3.1

# Custom sysroot base
espctl ide sync --sysroot /opt/espctl-sysroot

# Configure a project at a different path
espctl ide sync --project /home/me/my-app --idf-version v5.3.1

# Override server for one run (no login persisted)
espctl ide sync --server https://staging.esphome.cloud

Variable	Effect
`ESPCTL_SYSROOT`	Sysroot base override.
`ESPCTL_SERVER`	Server URL override.
`DEFAULT_IDF_VERSION`	Last-resort IDF version fallback.

See Environment Variable Index for the full list.

ESP-IDF MCP — User Manual