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