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
--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.
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
- --device UPLOAD_PORT¶
Manually specify the upload port/IP to use. For example
/dev/cu.SLAB_USBtoUART
, or192.168.1.176
to perform an OTA.
- --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 compile <CONFIG>
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 upload <CONFIG>
validates the configuration and uploads the most recent firmware build.
- --device UPLOAD_PORT¶
Manually specify the upload port/IP address to use. For example
/dev/cu.SLAB_USBtoUART
, or192.168.1.176
to perform an OTA.
- --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.
- --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.
- --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.
- --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
.
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.