ESPHome CLI Command Reference: Commands and Options

The ESPHome command-line interface (CLI) is the primary tool for compiling, uploading, and debugging firmware on ESP32, ESP8266, and RP2040 devices. Every operation — from first-flash to daily OTA updates — flows through a consistent command structure, and all commands accept one or more YAML configuration files as input.

Base Usage

esphome [OPTIONS] <COMMAND> <CONFIG> [ARGUMENTS]

You can pass multiple configuration files to most commands by listing them after the command name:

esphome run livingroom.yaml kitchen.yaml

ESPHome processes each file in sequence and reports success or failure for each one independently.

Global Options

Global options appear between esphome and the command name and apply to all commands.

-h, --help

flag

Print available commands and their arguments. You can also append --help to any specific command to see its flags:

esphome run --help

-v, --verbose

flag

Enable verbose ESPHome log output. Equivalent to setting the environment variable ESPHOME_VERBOSE=true.

-q, --quiet

flag

Suppress all ESPHome log output. Useful in CI pipelines where only exit codes matter.

-s, --substitution KEY VALUE

string (repeatable)

Define or override a substitution variable at the command line. May be specified multiple times. See Command-line Substitutions for details.

esphome -s name my_sensor -s board esp32dev compile device.yaml

--toolchain TOOLCHAIN

string

Select the toolchain used to compile the project. Accepted values:

platformio (default) — uses PlatformIO to manage the ESP-IDF/Arduino layers.
esp-idf — uses ESPHome’s native ESP-IDF integration with automatic framework installation.

If esp32.toolchain is also set in YAML, the CLI option takes precedence. See ESP-IDF Toolchain for details.

esphome --toolchain esp-idf compile my_device.yaml

Commands

`run`

The most commonly used command. It validates the configuration, compiles the firmware, uploads it to the device, and then streams logs.

esphome run <CONFIG> [OPTIONS]

Example:

esphome run my-sensor.yaml --device 192.168.1.100

--device DEVICE

string (repeatable)

Specify the port or IP address to use for upload and logging. Accepts:

A serial port path, e.g. /dev/cu.SLAB_USBtoUART or COM3
An IPv4 or IPv6 address for OTA, e.g. 192.168.1.176 or 2001:db8::1
The keyword OTA to auto-resolve the address via MQTT, DNS, or mDNS

Repeat the flag to supply fallback addresses — ESPHome tries each in order:

esphome run my-device.yaml --device 192.168.1.100 --device 2001:db8::1

--upload_speed BAUD_RATE

integer

Serial upload baud rate. Defaults to 460800 or the value of ESPHOME_UPLOAD_SPEED. Can also be set per-config in platformio_options.

--no-logs

flag

Skip opening the log view after a successful upload. Useful in scripts where you only need to flash the device.

--topic TOPIC

string

Override the MQTT topic used for log streaming.

--username USERNAME

string

MQTT username for log streaming.

--password PASSWORD

string

MQTT password for log streaming.

--client-id CLIENT_ID

string

MQTT client ID for log streaming. Defaults to a random value.

--host-port HOST_PORT

integer

Host port for legacy Over-the-Air upload connections.

--ota-platform {esphome,web_server}

string

Force a specific OTA platform. By default ESPHome uses whatever is configured in YAML. Use web_server when the native OTA password is lost but web server credentials are still known.

--reset

flag

Reset the device before the log view starts. Also configurable via ESPHOME_SERIAL_LOGGING_RESET=true.

`compile`

Validates the configuration and compiles the firmware without uploading it. Useful for CI checks or pre-building before deploying to a remote location.

esphome compile <CONFIG> [OPTIONS]

esphome compile my-sensor.yaml

--only-generate

flag

Only generate the C++ source files; do not run the actual compiler. The generated code lands in <NODE_NAME>/src/main.cpp.

Any command that accepts a YAML <CONFIG> also accepts a .esphomebundle.tar.gz bundle file produced by esphome bundle. The bundle is automatically extracted before the command runs.

`upload`

Uploads the most recently compiled firmware to a device without recompiling. Run esphome compile first.

esphome upload <CONFIG> [OPTIONS]

esphome upload my-sensor.yaml --device /dev/ttyUSB0

--device DEVICE

string (repeatable)

Serial port or IP address to upload to. Supports fallback addresses when repeated. See run --device for full details.

--upload_speed BAUD_RATE

integer

Baud rate for serial upload. Defaults to 460800.

--host-port HOST_PORT

integer

Host port for legacy OTA upload connections.

--ota-platform {esphome,web_server}

string

Force a specific OTA platform for this upload. See run --ota-platform for details.

`logs`

Streams log output from a device. ESPHome automatically selects the log transport — native API, MQTT, or serial — based on the configuration.

esphome logs <CONFIG> [OPTIONS]

esphome logs my-sensor.yaml --device 192.168.1.100

--device DEVICE

string (repeatable)

Serial port, IP address, or OTA. When using the native API for logs, multiple addresses are passed to the API client which uses the Happy Eyeballs algorithm (RFC 8305) to connect via the fastest available path.

esphome logs my-device.yaml --device 192.168.1.100 --device 2001:db8::1

--topic TOPIC

string

MQTT topic to subscribe to for log messages.

--username USERNAME

string

MQTT username.

--password PASSWORD

string

MQTT password.

--client-id CLIENT_ID

string

MQTT client ID.

--reset

flag

Reset the device before streaming logs. Also set via ESPHOME_SERIAL_LOGGING_RESET=true.

--no-states

flag

Suppress entity state-change lines ([S] prefix) from the native API log stream, showing only firmware log messages.

For devices in remote or inaccessible locations, use aioesphomeapi-logs (bundled with ESPHome) for API-based log streaming:

aioesphomeapi-logs 192.168.1.100
# With encryption
aioesphomeapi-logs 192.168.1.100 --noise-psk <your-api-key>

`config`

Validates the YAML configuration and prints the fully-resolved output, including all substitutions and packages. No compilation occurs.

esphome config <CONFIG>

esphome config my-sensor.yaml

`config-hash`

Loads the configuration, calculates a hash, and prints it. Compare the hash against the Version Text Sensor on a running device to confirm it is running the expected firmware.

esphome config-hash <CONFIG>

`dashboard`

Launches the ESPHome web dashboard — a browser-based UI for managing all your devices. This command accepts a directory of YAML files rather than a single configuration file.

esphome dashboard <CONFIG_DIR> [OPTIONS]

esphome dashboard ./config/ --port 6052 --open-ui

--port PORT

integer

HTTP port for the dashboard server. Defaults to 6052.

--address ADDRESS

string

Network address to bind to. Defaults to 0.0.0.0 (all interfaces).

--socket SOCKET

string

Unix socket path to bind to instead of a TCP port. Cannot be combined with --open-ui.

--username USERNAME

string

Optional username to require for HTTP Basic Auth on the dashboard.

--password PASSWORD

string

Optional password for HTTP Basic Auth.

--open-ui

flag

Automatically open the dashboard in a browser once the server is ready. Does not work with --socket.

`clean`

Removes all build artifacts for a configuration. Run this when switching frameworks or resolving stubborn build errors.

esphome clean <CONFIG>

esphome clean my-sensor.yaml

`clean-all`

Removes all build files, PlatformIO platform and package files, and the PlatformIO core directory. Unlike clean, a configuration file is optional — if none is provided, ESPHome cleans the .esphome directory in the current working directory.

esphome clean-all [<CONFIG>...]

Storage files (.json files and the storage directory inside .esphome) are preserved so the dashboard continues to function correctly.

`clean-mqtt`

Clears retained MQTT discovery messages from the MQTT broker. Useful when renaming or removing a device that was previously using MQTT discovery with Home Assistant.

esphome clean-mqtt <CONFIG> [OPTIONS]

--topic TOPIC

string

The MQTT topic to clear retained messages from. Defaults to the device’s configured MQTT discovery topic.

--username USERNAME

string

MQTT username.

--password PASSWORD

string

MQTT password.

--client-id CLIENT_ID

string

MQTT client ID.

`bundle`

Packages a YAML configuration and all its local dependencies into a self-contained .esphomebundle.tar.gz archive. Transfer the bundle to another machine for compilation with esphome compile device.esphomebundle.tar.gz.

esphome bundle <CONFIG> [OPTIONS]

esphome bundle my-device.yaml --output /tmp/my-device.esphomebundle.tar.gz

The bundle includes local !include files, secrets.yaml (filtered to referenced keys), fonts, images, certificates, and local external_components directories. Remote git-based resources are not bundled — they are fetched during compilation on the target machine.

-o, --output PATH

string

Custom output path for the bundle archive. Defaults to the config file path with .esphomebundle.tar.gz extension.

--list-only

flag

List all files that would be bundled without creating the archive.

`update-all`

Compiles and uploads firmware to all devices in a directory via OTA. Prints a summary of successes and failures at the end.

esphome update-all <CONFIG>...

esphome update-all ./config/

Internally this runs esphome run <CONFIG> --no-logs --device OTA for each device found.

`analyze-memory`

Compiles a configuration and analyzes flash and RAM usage by component. Useful for identifying memory bottlenecks, especially on memory-constrained devices like the ESP8266.

esphome analyze-memory <CONFIG>

This is an advanced command primarily intended for developers and contributors debugging memory issues.

`wizard`

Starts an interactive configuration creation wizard that guides you through setting up a new ESPHome node.

esphome wizard <CONFIG>

`version`

Prints the current ESPHome version and exits.

esphome version

Shell Auto-completion

ESPHome’s CLI supports tab-completion in Bash and ZSH via argcomplete. Register it by adding the following to your ~/.bashrc:

eval "$(register-python-argcomplete esphome)"

See the argcomplete documentation for more details.

Discovering Devices on the Network

Use aioesphomeapi-discover (bundled with ESPHome) to find all online ESPHome devices on the local network:

aioesphomeapi-discover

CLI & API

Advanced

ESPHome CLI Command Reference: Commands and Options

Base Usage

Global Options

Commands

`run`

`compile`

`upload`

`logs`

`config`

`config-hash`

`dashboard`

`clean`

`clean-all`

`clean-mqtt`

`bundle`

`update-all`

`analyze-memory`

`wizard`

`version`

Shell Auto-completion

Discovering Devices on the Network

Build docs developers (and LLMs) love

CLI & API

Advanced

Documentation Index

​Base Usage

​Global Options

​Commands

​run

​compile

​upload

​logs

​config

​config-hash

​dashboard

​clean

​clean-all

​clean-mqtt

​bundle

​update-all

​analyze-memory

​wizard

​version

​Shell Auto-completion

​Discovering Devices on the Network

Build docs developers (and LLMs) love

Base Usage

Global Options

Commands

`run`

`compile`

`upload`

`logs`

`config`

`config-hash`

`dashboard`

`clean`

`clean-all`

`clean-mqtt`

`bundle`

`update-all`

`analyze-memory`

`wizard`

`version`

Shell Auto-completion

Discovering Devices on the Network