Guide · command line · preview · Windows

Coil's tools on the command line.

Each of Coil's programs works on its own, without VS Code: in a terminal, in a script or in CI.

01The tools

The extension uses these, and you can run them yourself:

ToolWhat it does
coil-flashFlash an ESP-IDF build over JTAG: coil-flash [--serial <MAC>] <build folder>. --port COMx for serial, --esp-prog for an ESP-Prog, --dry-run only compares and writes nothing, --erase-all, --read <address> <length> <file> reads flash to a file, --write <address> <file> writes one back (only the 64 KB chunks that differ).
coil-monitorSerial monitor with panic decoding: coil-monitor --port <COMx> [--elf <app.elf> --addr2line <exe>]
coil-dapCoil's debug adapter (Debug Adapter Protocol), started by VS Code
coil-gdbGDB server for any GDB: coil-gdb [--serial <MAC>] [--port 3333]; monitor flash <build folder> flashes from GDB
coil-checkPin checker for CI: coil-check (--chip <chip> | --part <part>) --board-h <file>
coil-configProject settings without menuconfig: coil-config get|show|search|list|set|reset ... (below)
coil-newA new ESP-IDF project: coil-new <folder> [--chip esp32c6] [--template hello|blank|wifi-station] [--name NAME] (New project); --list shows the chips and templates; add <file> [--header] and unlisted for source files

coil-gdb takes --esp-prog (and --khz) for a board behind an ESP-Prog. The tools are in the extension's bin folder (%USERPROFILE%\.vscode\extensions\bluscape.coil-0.2.3\bin) once it's installed.

02Settings from the command line: coil-config

coil-config reads and changes your project's settings (the options menuconfig shows) without menuconfig. Run it in the project folder (or pass --project <folder>); the project needs a configured build folder.

coil-config get FREERTOS_HZ LOG_DEFAULT_LEVEL     # values, as in sdkconfig
coil-config show ESP_INT_WDT_TIMEOUT_MS           # where it comes from, what it needs, range, default, help
coil-config search watchdog task                  # by name, title or help, hidden options too
coil-config list --changed                        # only what you set
coil-config set FREERTOS_HZ=1000 ESP_INT_WDT=n    # change options (--dry-run to only see what would change)
coil-config reset FREERTOS_HZ                     # back to the default (sdkconfig.defaults still counts)

Names work with or without CONFIG_. set checks every value first and says why it can't be kept: out of range, hidden because another option is off ("needs CONFIG_ESP_INT_WDT (now n)"), selected by another option, or part of a choice. It lists every option that changes with it, and keeps the previous file as sdkconfig.old. Build afterwards to use the new settings. Add --json for output a script or a coding agent can read.

Reading is Coil's own Kconfig engine, about 60 ms for an ESP-IDF project. The file is written by ESP-IDF's own Kconfig library (with the build's Python), and Coil checks that it wrote exactly what Coil predicted, so the result is what menuconfig would give.