esphome-docs/guides/cli.rst

222 lines
5.3 KiB
ReStructuredText
Raw Normal View History

2018-11-03 16:21:10 +01:00
Command Line Interface
======================
2018-11-14 22:12:27 +01:00
.. seo::
2019-02-16 23:25:23 +01:00
:description: Documentation for the command line interface of ESPHome.
2018-11-14 22:12:27 +01:00
2018-11-03 16:21:10 +01:00
Base Usage
----------
2019-02-16 23:25:23 +01:00
ESPHome's command line interface always has the following format
2018-11-03 16:21:10 +01:00
.. code-block:: console
2018-11-03 16:21:10 +01:00
esphome [OPTIONS] <CONFIGURATION...> <COMMAND> [ARGUMENTS]
2019-07-28 12:41:15 +02:00
.. note::
You can specify multiple configuration files in the command line interface,
just list all files in front of the <COMMAND> like so:
.. code-block:: console
esphome livingroom.yaml kitchen.yaml run
``--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
2018-11-03 16:21:10 +01:00
``--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.
2018-11-03 16:21:10 +01:00
``run`` Command
---------------
2019-02-16 23:25:23 +01:00
The ``esphome <CONFIG> run`` command is the most common command for ESPHome. It
2018-11-03 16:21:10 +01:00
* Validates the configuration
* Compiles a firmware
* Uploads the firmware (over OTA or USB)
* Starts the log view
2019-02-16 23:25:23 +01:00
.. program:: esphome run
2018-11-10 15:29:50 +01:00
2018-11-03 16:21:10 +01:00
.. option:: --upload-port UPLOAD_PORT
Manually specify the upload port/ip to use. For example ``/dev/cu.SLAB_USBtoUART``.
.. 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
------------------
2019-02-16 23:25:23 +01:00
.. program:: esphome config
2018-11-10 15:29:50 +01:00
2019-02-16 23:25:23 +01:00
The ``esphome <CONFIG> config`` validates the configuration and displays the validation result.
2018-11-03 16:21:10 +01:00
``compile`` Command
-------------------
2019-02-16 23:25:23 +01:00
.. program:: esphome compile
2018-11-10 15:29:50 +01:00
2019-02-16 23:25:23 +01:00
The ``esphome <CONFIG> compile`` validates the configuration and compiles the firmware.
2018-11-03 16:21:10 +01:00
.. option:: --only-generate
If set, only generates the C++ source code and does not compile the firmware.
``upload`` Command
------------------
2019-02-16 23:25:23 +01:00
.. program:: esphome upload
2018-11-10 15:29:50 +01:00
2019-02-16 23:25:23 +01:00
The ``esphome <CONFIG> upload`` validates the configuration and uploads the most recent firmware build.
2018-11-03 16:21:10 +01:00
.. option:: --upload-port UPLOAD_PORT
2020-05-10 21:27:59 +02:00
Manually specify the upload port/IP to use. For example ``/dev/cu.SLAB_USBtoUART``.
2018-11-03 16:21:10 +01:00
.. option:: --host-port HOST_PORT
Specify the host port to use for legacy Over the Air uploads.
``clean-mqtt`` Command
----------------------
2019-02-16 23:25:23 +01:00
.. program:: esphome clean-mqtt
2018-11-10 15:29:50 +01:00
2019-02-16 23:25:23 +01:00
The ``esphome <CONFIG> clean-mqtt`` cleans retained MQTT discovery messages from the MQTT broker.
2018-11-03 16:21:10 +01:00
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
------------------
2019-02-16 23:25:23 +01:00
.. program:: esphome wizard
2018-11-10 15:29:50 +01:00
2020-05-10 21:27:59 +02:00
The ``esphome <CONFIG> wizard`` command starts the ESPHome configuration creation wizard.
2018-11-03 16:21:10 +01:00
``mqtt-fingerprint`` Command
----------------------------
2019-02-16 23:25:23 +01:00
.. program:: esphome mqtt-fingerprint
2018-11-10 15:29:50 +01:00
2019-02-16 23:25:23 +01:00
The ``esphome <CONFIG> mqtt-fingerprint`` command shows the MQTT SSL fingerprints of the remote used
2018-11-03 16:21:10 +01:00
for SSL MQTT connections. See :ref:`mqtt-ssl_fingerprints`.
``version`` Command
-------------------
2019-02-16 23:25:23 +01:00
.. program:: esphome version
2018-11-10 15:29:50 +01:00
2019-02-16 23:25:23 +01:00
The ``esphome <CONFIG> version`` command shows the current ESPHome version and exits.
2018-11-03 16:21:10 +01:00
``clean`` Command
-----------------
2019-02-16 23:25:23 +01:00
.. program:: esphome clean
2018-11-10 15:29:50 +01:00
2019-02-16 23:25:23 +01:00
The ``esphome <CONFIG> clean`` command cleans all build files and can help with some build issues.
2018-11-03 16:21:10 +01:00
``hass-config`` Command
-----------------------
2019-02-16 23:25:23 +01:00
.. program:: esphome hass-config
2018-11-10 15:29:50 +01:00
2019-02-16 23:25:23 +01:00
The ``esphome <CONFIG> hass-config`` command shows an auto-generated Home Assistant configuration for the ESPHome
2018-11-03 16:21:10 +01:00
node configuration file. This is useful if you're not using MQTT discovery.
``dashboard`` Command
---------------------
2019-02-16 23:25:23 +01:00
.. program:: esphome dashboard
2018-11-10 15:29:50 +01:00
2020-05-10 21:27:59 +02:00
The ``esphome <CONFIG> dashboard`` command starts the ESPHome dashboard server for using ESPHome
2018-11-03 16:21:10 +01:00
through a graphical user interface.
.. option:: --port PORT
2018-11-10 15:29:50 +01:00
Manually set the HTTP port to open connections on (defaults to 6052)
2018-11-03 16:21:10 +01:00
.. option:: --username USERNAME
The optional username to require for authentication.
2018-11-03 16:21:10 +01:00
.. option:: --password PASSWORD
The optional password to require for authentication.
2018-11-03 16:21:10 +01:00
.. option:: --open-ui
If set, opens the dashboard UI in a browser once the server is up and running.