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.

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

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

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