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 like so:

esphome run livingroom.yaml kitchen.yaml

`--help` Option

-h|--help

Output possible 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, or 192.168.1.176 to perform an OTA.

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

--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, or 192.168.1.176 to perform an OTA.

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

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

--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 External link documentation.

CURRENT