256 lines
6.2 KiB
ReStructuredText
256 lines
6.2 KiB
ReStructuredText
Command Line Interface
|
|
======================
|
|
|
|
.. seo::
|
|
:description: Documentation for the command line interface of ESPHome.
|
|
|
|
Base Usage
|
|
----------
|
|
|
|
ESPHome's command line interface always has the following format
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
esphome run livingroom.yaml kitchen.yaml
|
|
|
|
``--help`` Option
|
|
--------------------
|
|
|
|
.. option:: -h|--help
|
|
|
|
Output possible <commands> and [arguments].
|
|
Note: you can also use ``--help`` for any command to get arguments specific to that command.
|
|
.. code-block:: console
|
|
|
|
esphome <some_command> --help
|
|
|
|
``--verbose`` Option
|
|
--------------------
|
|
|
|
.. option:: -v|--verbose
|
|
|
|
Enable verbose esphome logs.
|
|
|
|
``--quiet`` Option
|
|
------------------
|
|
|
|
.. option:: -q|--quiet
|
|
|
|
Disable all esphome logs.
|
|
|
|
``--substitution`` Option
|
|
-------------------------
|
|
|
|
*(can be issued multiple times)*
|
|
|
|
.. option:: -s|--substitution KEY VALUE
|
|
|
|
Defines or overrides substitution KEY with value VALUE.
|
|
|
|
Please see :ref:`command line substitutions <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
|
|
|
|
.. program:: esphome run
|
|
|
|
.. option:: --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.
|
|
|
|
.. option:: --no-logs
|
|
|
|
Disable starting log view.
|
|
|
|
.. option:: --topic TOPIC
|
|
|
|
Manually set the topic to subscribe to for MQTT logs (defaults to the one in the configuration).
|
|
|
|
.. option:: --username USERNAME
|
|
|
|
Manually set the username to subscribe with for MQTT logs (defaults to the one in the configuration).
|
|
|
|
.. option:: --password PASSWORD
|
|
|
|
Manually set the password to subscribe with for MQTT logs (defaults to the one in the configuration).
|
|
|
|
.. option:: --client-id CLIENT_ID
|
|
|
|
Manually set the client ID to subscribe with for MQTT logs (defaults to a randomly chosen one).
|
|
|
|
.. option:: --host-port HOST_PORT
|
|
|
|
Specify the host port to use for legacy Over the Air uploads.
|
|
|
|
``config`` Command
|
|
------------------
|
|
|
|
.. program:: esphome config
|
|
|
|
The ``esphome config <CONFIG>`` validates the configuration and displays the validation result.
|
|
|
|
|
|
``compile`` Command
|
|
-------------------
|
|
|
|
.. program:: esphome compile
|
|
|
|
The ``esphome compile <CONFIG>`` validates the configuration and compiles the firmware.
|
|
|
|
.. option:: --only-generate
|
|
|
|
If set, only generates the C++ source code and does not compile the firmware.
|
|
|
|
``upload`` Command
|
|
------------------
|
|
|
|
.. program:: esphome upload
|
|
|
|
The ``esphome upload <CONFIG>`` validates the configuration and uploads the most recent firmware build.
|
|
|
|
.. option:: --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.
|
|
|
|
.. option:: --host-port HOST_PORT
|
|
|
|
Specify the host port to use for legacy Over the Air uploads.
|
|
|
|
``clean-mqtt`` Command
|
|
----------------------
|
|
|
|
.. program:: esphome clean-mqtt
|
|
|
|
The ``esphome clean-mqtt <CONFIG>`` cleans retained MQTT discovery messages from the MQTT broker.
|
|
See :ref:`mqtt-using_with_home_assistant`.
|
|
|
|
.. option:: --topic TOPIC
|
|
|
|
Manually set the topic to clean retained messages from (defaults to the MQTT discovery topic of the
|
|
node).
|
|
|
|
.. option:: --username USERNAME
|
|
|
|
Manually set the username to subscribe with.
|
|
|
|
.. option:: --password PASSWORD
|
|
|
|
Manually set the password to subscribe with.
|
|
|
|
.. option:: --client-id CLIENT_ID
|
|
|
|
Manually set the client ID to subscribe with.
|
|
|
|
``wizard`` Command
|
|
------------------
|
|
|
|
.. program:: esphome wizard
|
|
|
|
The ``esphome wizard <CONFIG>`` command starts the ESPHome configuration creation wizard.
|
|
|
|
``mqtt-fingerprint`` Command
|
|
----------------------------
|
|
|
|
.. program:: esphome mqtt-fingerprint
|
|
|
|
The ``esphome mqtt-fingerprint <CONFIG>`` command shows the MQTT SSL fingerprints of the remote used
|
|
for SSL MQTT connections. See :ref:`mqtt-ssl_fingerprints`.
|
|
|
|
``version`` Command
|
|
-------------------
|
|
|
|
.. program:: esphome version
|
|
|
|
The ``esphome version`` command shows the current ESPHome version and exits.
|
|
|
|
``clean`` Command
|
|
-----------------
|
|
|
|
.. program:: esphome clean
|
|
|
|
The ``esphome clean <CONFIG>`` command cleans all build files and can help with some build issues.
|
|
|
|
``dashboard`` Command
|
|
---------------------
|
|
|
|
.. program:: esphome dashboard
|
|
|
|
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.
|
|
|
|
.. option:: --port PORT
|
|
|
|
Manually set the HTTP port to open connections on (defaults to 6052)
|
|
|
|
.. option:: --username USERNAME
|
|
|
|
The optional username to require for authentication.
|
|
|
|
.. option:: --password PASSWORD
|
|
|
|
The optional password to require for authentication.
|
|
|
|
.. option:: --open-ui
|
|
|
|
If set, opens the dashboard UI in a browser once the server is up and running.
|
|
|
|
``logs`` Command
|
|
---------------------
|
|
|
|
.. program:: esphome logs
|
|
|
|
The ``esphome logs <CONFIG>`` command validates the configuration and shows all logs.
|
|
|
|
.. option:: --topic TOPIC
|
|
|
|
Manually set the topic to subscribe to.
|
|
|
|
.. option:: --username USERNAME
|
|
|
|
Manually set the username.
|
|
|
|
.. option:: --password PASSWORD
|
|
|
|
Manually set the password.
|
|
|
|
.. option:: --client-id CLIENT_ID
|
|
|
|
Manually set the client id.
|
|
|
|
.. option:: --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:
|
|
|
|
.. code-block:: console
|
|
|
|
eval "$(register-python-argcomplete esphome)"
|
|
|
|
For more information, see `argcomplete <https://kislyuk.github.io/argcomplete/>`__ documentation.
|
|
|