Command Line Interface

Base Usage

ESPHome’s command line interface always has the following format

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

Note

You can specify multiple configuration files in the command line interface, just list all files in front of the <COMMAND> like so:

esphome livingroom.yaml kitchen.yaml run

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

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

run Command

The esphome <CONFIG> run 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

--upload-port UPLOAD_PORT

Manually specify the upload port/ip to use. For example /dev/cu.SLAB_USBtoUART.

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

config Command

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

compile Command

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

--only-generate

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

upload Command

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

--upload-port UPLOAD_PORT

Manually specify the upload port/IP to use. For example /dev/cu.SLAB_USBtoUART.

--host-port HOST_PORT

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

clean-mqtt Command

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

--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 <CONFIG> wizard command starts the ESPHome configuration creation wizard.

mqtt-fingerprint Command

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

version Command

The esphome <CONFIG> version command shows the current ESPHome version and exits.

clean Command

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

hass-config Command

The esphome <CONFIG> hass-config command shows an auto-generated Home Assistant configuration for the ESPHome node configuration file. This is useful if you’re not using MQTT discovery.

dashboard Command

The esphome <CONFIG> dashboard command starts the ESPHome dashboard server for using ESPHome through a graphical user interface.

--port PORT

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

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

logs Command

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

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

--serial-port SERIAL_PORT

Manually specify a serial port to use. For example /dev/cu.SLAB_USBtoUART.