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

--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.

`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: