Command Line Interface

Base Usage

ESPHome’s command line interface always has the following format

esphome [OPTIONS] <COMMAND> <CONFIGURATION...> [ARGUMENTS]

NOTE

You can specify multiple configuration files in the command line interface for some commands, just list all files after the <COMMAND> like so:

esphome run livingroom.yaml kitchen.yaml

Options

--help Option

-h|--help : Output possible <commands> and [arguments]. Note: you can also use --help for any command to get arguments specific to that command.

esphome <some_command> --help

--verbose Option

-v|--verbose : Enable verbose esphome logs. Can also be enabled via environment variable ESPHOME_VERBOSE=true.

--quiet Option

-q|--quiet : Disable all esphome logs.

--substitution Option

Can be issued multiple times.

-s|--substitution KEY VALUE : Defines or overrides substitution KEY with value VALUE.

Please see command line substitutions for details.

Commands

run Command

The esphome run <CONFIG> command is the most common command for ESPHome. It

• Validates the configuration
• Compiles a firmware
• Uploads the firmware (over OTA or USB)
• Starts the log view

Options

--device UPLOAD_PORT : Manually specify the upload port/IP to use. For example /dev/cu.SLAB_USBtoUART, or 192.168.1.176 to perform an OTA.

Multiple --device options can be specified to provide fallback addresses. ESPHome will try each address in order until one succeeds. This is particularly useful for devices with multiple IP addresses (IPv4/IPv6).

Example:

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

--upload_speed BAUD_RATE : The upload speed for serial flashing defaults to 460800 or as set with the environment variable ESPHOME_UPLOAD_SPEED. This can be overridden in the platformio options on a per-config basis, or set with this option at the time of uploading.

--no-logs : Disable starting log view.

--topic TOPIC : Manually set the topic to subscribe to for MQTT logs (defaults to the one in the configuration).

--username USERNAME : Manually set the username to subscribe with for MQTT logs (defaults to the one in the configuration).

--password PASSWORD : Manually set the password to subscribe with for MQTT logs (defaults to the one in the configuration).

--client-id CLIENT_ID : Manually set the client ID to subscribe with for MQTT logs (defaults to a randomly chosen one).

--host-port HOST_PORT : Specify the host port to use for legacy Over the Air uploads.

--reset : If set, reset the device before starting the logs. May also be configured with the environment variable ESPHOME_SERIAL_LOGGING_RESET=true.

config Command

The esphome config <CONFIG> validates the configuration and displays the validation result.

compile Command

The esphome compile <CONFIG> validates the configuration and compiles the firmware.

Options

--only-generate : If set, only generates the C++ source code and does not compile the firmware.

upload Command

The esphome upload <CONFIG> validates the configuration and uploads the most recent firmware build.

Options

--device UPLOAD_PORT : Manually specify the upload port/IP address to use. For example /dev/cu.SLAB_USBtoUART, or 192.168.1.176 to perform an OTA.

Multiple --device options can be specified to provide fallback addresses. ESPHome will try each address in order until one succeeds.

Example:

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

--upload_speed BAUD_RATE : The upload speed for serial flashing defaults to 460800 or as set with the environment variable ESPHOME_UPLOAD_SPEED. This can be overridden in the platformio options on a per-config basis, or set with this option at the time of uploading.

--host-port HOST_PORT : Specify the host port to use for legacy Over the Air uploads.

clean-mqtt Command

The esphome clean-mqtt <CONFIG> cleans retained MQTT discovery messages from the MQTT broker. See Using with Home Assistant MQTT entities.

Options

--topic TOPIC : Manually set the topic to clean retained messages from (defaults to the MQTT discovery topic of the node).

--username USERNAME : Manually set the username to subscribe with.

--password PASSWORD : Manually set the password to subscribe with.

--client-id CLIENT_ID : Manually set the client ID to subscribe with.

wizard Command

The esphome wizard <CONFIG> command starts the ESPHome configuration creation wizard.

mqtt-fingerprint Command

The esphome mqtt-fingerprint <CONFIG> command shows the MQTT SSL fingerprints of the remote used for SSL MQTT connections. See SSL Fingerprints.

version Command

The esphome version command shows the current ESPHome version and exits.

clean Command

The esphome clean <CONFIG> command cleans all build files and can help with some build issues.

dashboard Command

The esphome dashboard <CONFIG> command starts the ESPHome dashboard server for using ESPHome through a graphical user interface. This command accepts a configuration directory instead of a single configuration file.

Options

--address ADDRESS : Manually set the address to bind to (defaults to 0.0.0.0)

--port PORT : Manually set the HTTP port to open connections on (defaults to 6052)

--socket SOCKET : Manually set the unix socket to bind to. If specified along with --address or --port the values for those parameters will be ignored. Cannot be used along with --systemd-socket.

--username USERNAME : The optional username to require for authentication.

--password PASSWORD : The optional password to require for authentication.

--open-ui : If set, opens the dashboard UI in a browser once the server is up and running. Does not work when using --socket.

analyze-memory Command

NOTE

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

The esphome analyze-memory <CONFIG> command compiles the configuration and analyzes memory usage by component.

This command is useful for:

• Understanding which components are consuming the most memory
• Identifying optimization opportunities to reduce flash or RAM usage
• Analyzing memory usage before adding more components to a tight build
• Debugging builds that are approaching memory limits (especially on ESP8266)
• Contributing to ESPHome development and optimization efforts

The command automatically compiles the configuration if needed (or quickly relinks if sources haven’t changed), then analyzes the resulting firmware to show a detailed breakdown of memory usage by component, including flash memory (code and data) and RAM usage (data and BSS).

logs Command

The esphome logs <CONFIG> command validates the configuration and shows all logs.

Options

--topic TOPIC : Manually set the topic to subscribe to.

--username USERNAME : Manually set the username.

--password PASSWORD : Manually set the password.

--client-id CLIENT_ID : Manually set the client id.

--device SERIAL_PORT : Manually specify a serial port/IP to use. For example /dev/cu.SLAB_USBtoUART.

Multiple --device options can be specified to provide fallback addresses. When using the native API for logs, all addresses are passed to the API client which uses the Happy Eyeballs algorithm (RFC 8305) to efficiently connect using the fastest available address.

Example:

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

--reset : If set, reset the device before starting the logs. May also be configured with the environment variable ESPHOME_SERIAL_LOGGING_RESET=true.

Using Bash or ZSH auto-completion

ESPHome’s command line interface provides the ability to use auto-completion features provided by Bash or ZSH.

You can register ESPHome for auto-completion by adding the following to your ~/.bashrc file:

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

For more information, see argcomplete documentation.

Using logging tools supplied with ESPHome

There are two types of logging interfaces supplied with ESPHome: API and Serial (UART) logging. For serial logging, there are many options including ESPHome Web and the ESPHome CLI’s run command.

For basic API based logging uses, one can use the aioesphomeapi-logs command bundled with ESPHome, Which is especially useful for ESP devices in a remote/inaccessible location.

The syntax is as follows:

aioesphomeapi-logs <IPv4 pr IPv6 address>

Some working examples include:

aioesphomeapi-logs 192.168.x.y
aioesphomeapi-logs fe80::cdef:0123:4567:89ab
aioesphomeapi-logs 2001:0db8:3333:4444:5555:6666:7777:8888

Press CTRL+C to exit the logging view.

If you have configured encryption for API, provide the key from the yaml as follows:

aioesphomeapi-logs 192.168.x.y --noise-psk <your-api-key-from-yaml>

If you do not know/wish to know the IP address of an ESPHome device, one can also use aioesphomeapi-discover to discover online ESPHome devices on the local network.

The syntax is as follows:

aioesphomeapi-discover

The response lists info about currently available ESPHome devices:

Status |Name |Address |MAC |Version |Platform |Board

See Also

• Guides