命令行界面

基本使用

ESPHome 的命令行界面始终具有以下格式

esphome [选项] <命令> <配置文件...> [参数]

ℹ️ Note
对于某些命令，您可以在命令行界面中指定多个配置文件，只需在 <命令> 后面列出所有文件，例如：
esphome run livingroom.yaml kitchen.yaml

选项

`--help` 选项

-h|--help

输出可能的 <命令> 和 [参数]。注意：您也可以使用 --help 获取任何特定命令的参数。

esphome <某个命令> --help

`--verbose` 选项

-v|--verbose

启用 verbose esphome 日志。也可以通过环境变量 ESPHOME_VERBOSE=true 启用。

`--quiet` 选项

-q|--quiet

禁用所有 esphome 日志。

`--substitution` 选项

可以多次发出。

-s|--substitution KEY VALUE

用值 VALUE 定义或覆盖替换 KEY。

请参阅命令行替换获取详细信息。

命令

`run` 命令

esphome run <配置> 命令是 ESPHome 最常用的命令。它

验证配置
编译固件
上传固件（通过 OTA 或 USB）
启动日志查看

选项

--device UPLOAD_PORT

手动指定要使用的上传端口/IP。例如 /dev/cu.SLAB_USBtoUART，或 192.168.1.176 以执行 OTA。

可以指定多个 --device 选项以提供备用地址。ESPHome 将按顺序尝试每个地址，直到成功。这对于具有多个 IP 地址（IPv4/IPv6）的设备特别有用。

示例：

esphome run my-device.yaml --device 192.168.1.100 --device 2001:db8::1

--upload_speed BAUD_RATE

串行闪存的上传速度默认为 460800 或通过环境变量 ESPHOME_UPLOAD_SPEED 设置。这可以在每个配置的平台io选项中覆盖，或在上传时使用此选项设置。

--no-logs

禁用启动日志查看。

--topic TOPIC

手动设置要订阅的 MQTT 日志主题（默认为配置中的主题）。

--username USERNAME

手动设置用于 MQTT 日志的订阅用户名（默认为配置中的用户名）。

--password PASSWORD

手动设置用于 MQTT 日志的订阅密码（默认为配置中的密码）。

--client-id CLIENT_ID

手动设置用于 MQTT 日志的订阅客户端 ID（默认为随机选择的一个）。

--host-port HOST_PORT

指定用于传统无线上传的主机端口。

--reset

如果设置，则在启动日志之前重置设备。也可以通过环境变量 ESPHOME_SERIAL_LOGGING_RESET=true 配置。

`config` 命令

esphome config <配置> 验证配置并显示验证结果。

`compile` 命令

esphome compile <配置> 验证配置并编译固件。

选项

--only-generate

如果设置，则仅生成 C++ 源代码，而不编译固件。

`upload` 命令

esphome upload <配置> 验证配置并上传最新的固件构建。

选项

--device UPLOAD_PORT

手动指定要使用的上传端口/IP地址。例如 /dev/cu.SLAB_USBtoUART，或 192.168.1.176 以执行 OTA。

可以指定多个 --device 选项以提供备用地址。ESPHome 将按顺序尝试每个地址，直到成功。

示例：

esphome upload my-device.yaml --device 192.168.1.100 --device 2001:db8::1

--upload_speed BAUD_RATE

串行闪发的上传速度默认为 460800 或通过环境变量 ESPHOME_UPLOAD_SPEED 设置。这可以在每个配置的平台io选项中覆盖，或在上传时使用此选项设置。

--host-port HOST_PORT

指定用于传统无线上传的主机端口。

`clean-mqtt` 命令

esphome clean-mqtt <配置> 清除 MQTT 中继消息的保留消息。参见与 Home Assistant MQTT 实体一起使用。

选项

--topic TOPIC

手动设置要清除保留消息的主题（默认为节点的 MQTT 发现主题）。

--username USERNAME

手动设置用于订阅的用户名。

--password PASSWORD

手动设置用于订阅的密码。

--client-id CLIENT_ID

手动设置用于订阅的客户端 ID。

`wizard` 命令

esphome wizard <配置> 命令启动 ESPHome 配置创建向导。

`mqtt-fingerprint` 命令

esphome mqtt-fingerprint <配置> 命令显示用于 SSL MQTT 连接的远程 MQTT SSL 指纹。参见 SSL 指纹。

`version` 命令

esphome version 命令显示当前 ESPHome 版本并退出。

`clean` 命令

esphome clean <配置> 命令清除所有构建文件，并有助于解决一些构建问题。

`dashboard` 命令

esphome dashboard <配置> 命令启动 ESPHome 仪表板服务器，以便通过图形用户界面使用 ESPHome。此命令接受配置目录而不是单个配置文件。

选项

--address ADDRESS

手动设置绑定地址（默认为 0.0.0.0）

--port PORT

手动设置用于打开连接的 HTTP 端口（默认为 6052）

--socket SOCKET

手动设置要绑定的 Unix 套接字。如果指定了 --address 或 --port，则这些参数的值将被忽略。不能与 --systemd-socket 一起使用。

--username USERNAME

需要身份验证的可选用户名。

--password PASSWORD

需要身份验证的可选密码。

--open-ui

如果设置，则在服务器启动并运行后打开仪表板 UI。当使用 --socket 时，此功能无效。

`logs` 命令

esphome logs <配置> 命令验证配置并显示所有日志。

选项

--topic TOPIC

手动设置要订阅的主题。

--username USERNAME

手动设置用户名。

--password PASSWORD

手动设置密码。

--client-id CLIENT_ID

手动设置客户端 ID。

--device SERIAL_PORT

手动指定要使用的串行端口/IP。例如 /dev/cu.SLAB_USBtoUART。

可以指定多个 --device 选项以提供备用地址。当使用原生日志 API 时，所有地址都会传递给 API 客户端，该客户端使用 Happy Eyeballs 算法（RFC 8305）以最高效的方式连接使用可用的最快地址。

示例：

esphome logs my-device.yaml --device 192.168.1.100 --device 2001:db8::1

--reset

如果设置，则在启动日志之前重置设备。也可以通过环境变量 ESPHOME_SERIAL_LOGGING_RESET=true 配置。

使用 Bash 或 ZSH 自动补全

ESPHome 的命令行界面提供了使用 Bash 或 ZSH 提供的自动补全功能的能力。

您可以通过在您的 ~/.bashrc 文件中添加以下内容来注册 ESPHome 进行自动补全：

eval "$(register-python-argcomplete esphome)"

有关更多信息，请参阅 argcomplete 文档。

使用 ESPHome 提供的日志工具

ESPHome 提供了两种类型的日志接口：API 和串行（UART）日志。对于串行日志，有许多选项，包括 ESPHome Web 和 ESPHome CLI 的 run 命令。

对于基本的基于 API 的日志使用，可以使用 ESPHome 预装的 aioesphomeapi-logs 命令，这在 ESP 设备位于远程/无法访问的位置时特别有用。

语法如下：

aioesphomeapi-logs <IPv4 或 IPv6 地址>

一些工作示例包括：

aioesphomeapi-logs 192.168.x.y
aioesphomeapi-logs fe80::cdef:0123:4567:89ab
aioesphomeapi-logs 2001:0db8:3333:4444:5555:6666:7777:8888

按 CTRL+C 退出日志查看。

如果您为 API 配置了加密，请按以下方式提供 YAML 中的密钥：

aioesphomeapi-logs 192.168.x.y --noise-psk <您的 API 密钥>

如果您不知道/不希望知道 ESPHome 设备的 IP 地址，您也可以使用 aioesphomeapi-discover 来发现本地网络上的在线 ESPHome 设备。

语法如下：

aioesphomeapi-discover

响应列出了当前可用的 ESPHome 设备的信息：

状态 |名称 |地址 |MAC |版本 |平台 |主板

参见

指南