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, or 192.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, or 192.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.