命令行界面

基本用法

ESPHome 的命令行界面始终采用以下格式

esphome [OPTIONS] <COMMAND> <CONFIGURATION...> [ARGUMENTS]

NOTE

你可以在命令行界面中为某些命令指定多个配置文件， 只需在 <COMMAND> 后列出所有文件，如下所示：

esphome run livingroom.yaml kitchen.yaml

选项

--help 选项

-h|--help : 输出可能的 <commands> 和 [arguments]。 注意：你也可以对任何命令使用 --help 来获取该命令特有的参数。

esphome <some_command> --help

--verbose 选项

-v|--verbose : 启用详细的 esphome 日志。 也可以通过环境变量 ESPHOME_VERBOSE=true 启用。

--quiet 选项

-q|--quiet : 禁用所有 esphome 日志。

--substitution 选项

可以多次指定。

-s|--substitution KEY VALUE : 定义或覆盖替换 KEY，值为 VALUE。

详情请参见命令行替换。

--toolchain 选项

--toolchain TOOLCHAIN : 选择用于编译项目的工具链。支持的值有：

• esp-idf（仅限 ESP32）
• platformio

工具链可以通过 esp32.toolchain 进行配置（参见 ESP32 工具链配置）。 如果未指定，ESP32 设备默认为 esp-idf；所有其他平台使用 platformio。 如果同时设置了 esp32.toolchain 和 --toolchain CLI 选项，则 CLI 选项优先。

有关使用 ESP-IDF 集成的详情，请参见 ESP-IDF 工具链文档。

命令

run 命令

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

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

选项

--device DEVICE : 手动指定用于上传和日志记录的端口/IP。例如 /dev/cu.SLAB_USBtoUART 或 192.168.1.176 用于执行 OTA。你也可以指定 OTA 以从 MQTT、DNS 或 mDNS 解析地址。 当存在多个选项时，这可以防止交互式提示。

可以指定多个 --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 的设置。 这可以在 platformio 选项中按配置覆盖，或在上传时使用此选项设置。

--no-logs : 禁用启动日志视图。

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

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

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

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

--host-port HOST_PORT : 指定用于传统无线（Over the Air）上传的主机端口。

--reset : 如果设置，在启动日志前重置设备。也可以通过环境变量 ESPHOME_SERIAL_LOGGING_RESET=true 进行配置。

--no-states / --states : 控制是否在日志输出中显示实体状态变化。详情请参见 logs 命令。默认值可以通过环境变量 ESPHOME_LOG_STATES 设置。

config 命令

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

选项

--show-secrets : 在输出中显示密钥值，而不是将其隐藏。

--no-defaults : 仅输出用户编写的配置，不包含模式验证填充的默认值。 对于共享最小复现示例或比较两个配置（无需数百个默认键干扰）非常有用。 替换、包及 !extend / !remove 将在输出中被解析。

config-hash 命令

esphome config-hash <CONFIG> 加载配置并计算哈希值，你可以将其与运行中设备上版本文本传感器的哈希值进行比较。

compile 命令

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

任何接受 <CONFIG> 的命令也可以接受 .esphomebundle.tar.gz 捆绑文件来代替 YAML 配置。该捆绑文件会在命令运行前自动解压。详情请参见 bundle 命令。

选项

--only-generate : 如果设置，仅生成 C++ 源代码，不编译固件。

upload 命令

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

选项

--device DEVICE : 手动指定上传端口/IP 地址。例如 /dev/cu.SLAB_USBtoUART 或 192.168.1.176 用于执行 OTA。你也可以指定 OTA 以从 MQTT、DNS 或 mDNS 解析地址。 当存在多个选项时，这可以防止交互式提示。

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

示例：

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

--upload_speed BAUD_RATE : 串行刷写的上传速度默认为 460800 或按照环境变量 ESPHOME_UPLOAD_SPEED 的设置。 这可以在 platformio 选项中按配置覆盖，或在上传时使用此选项设置。

--host-port HOST_PORT : 指定用于传统无线（Over the Air）上传的主机端口。

--ota-platform {esphome,web_server} : run 也接受此选项。在上传固件时强制指定特定的 OTA 平台。 默认情况下，ESPHome 使用设备 YAML 中配置的 OTA 平台；如果同时配置了 platform: esphome 和 platform: web_server，则优先使用原生的 esphome 协议。使用 --ota-platform web_server 可通过 Web Server OTA 平台 上传——例如， 当 OTA 密码丢失但 web_server auth 凭据仍然已知时。

clean-mqtt 命令

esphome clean-mqtt <CONFIG> 清理 MQTT 代理中保留的 MQTT 发现消息。 请参见与 Home Assistant MQTT 实体一起使用。

选项

--topic TOPIC : 手动设置要清理保留消息的主题（默认为该节点的 MQTT 发现主题）。

--username USERNAME : 手动设置用于订阅的用户名。

--password PASSWORD : 手动设置用于订阅的密码。

--client-id CLIENT_ID : 手动设置用于订阅的客户端 ID。

wizard 命令

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

version 命令

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

clean 命令

esphome clean <CONFIG> 命令清理所有构建文件，有助于解决某些构建问题。

clean-all 命令

esphome clean-all [<CONFIG>...] 命令清理所有构建文件、PlatformIO 平台和包文件，以及 PlatformIO 核心目录。与 clean 不同，此命令不需要配置文件——如果未提供配置文件，它将清理当前工作目录中的 .esphome 目录。参数可以是 YAML 配置文件或包含配置文件的目录。

存储文件（.json 文件和 .esphome 内的 storage 目录）将被保留，以便 ESPHome 设备构建器继续正常运行。

dashboard 命令

NOTE

内置的 dashboard 命令已被移除。要通过图形用户界面使用 ESPHome，请运行 ESPHome 设备构建器。Home Assistant 应用和 Docker 用户不受影响。两者都已运行设备构建器。

analyze-memory 命令

NOTE

这是一个高级命令，主要用于开发人员和调试内存问题。

esphome analyze-memory <CONFIG> 命令编译配置并按组件分析内存使用情况。

此命令适用于：

• 了解哪些组件消耗最多内存
• 识别优化机会以减少闪存或 RAM 使用
• 在向紧张的构建添加更多组件之前分析内存使用情况
• 调试接近内存限制的构建（特别是在 ESP8266 上）
• 为 ESPHome 开发和优化工作做出贡献

该命令会自动编译配置（如果需要），或者如果源文件未更改则快速重新链接，然后分析生成的固件，显示按组件划分的详细内存使用情况，包括闪存（代码和数据）以及 RAM 使用情况（数据和 BSS）。

bundle 命令

esphome bundle <CONFIG> 命令将 YAML 配置及其所有本地依赖项打包成一个独立的 .esphomebundle.tar.gz 归档文件。这对于远程编译非常有用——该捆绑包可以传输到另一台机器并使用 esphome compile device.esphomebundle.tar.gz 进行编译。

捆绑包包括：

• 主 YAML 配置文件
• 所有 !include 的 YAML 文件和 secrets.yaml（仅过滤引用的键）
• 字体、图像和动画文件
• 证书和密钥文件（例如用于 WPA2 EAP）
• 来自 esphome: includes: 的 C/C++ 包含文件
• Web 服务器 CSS/JS 包含文件
• 本地 external_components 目录

远程资源（基于 git 的外部组件、在线字体等）不会被捆绑——它们将在目标机器上编译时获取。

esphome bundle my-device.yaml

选项

-o/--output PATH : 指定捆绑归档文件的自定义输出路径。如果未指定，捆绑包将在配置文件旁边创建，扩展名为 .esphomebundle.tar.gz。

--list-only : 列出所有已发现将要包含在捆绑包中的文件，但不创建归档文件。用于验证将要打包的文件。

logs 命令

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

选项

--topic TOPIC : 手动设置要订阅的主题。

--username USERNAME : 手动设置用户名。

--password PASSWORD : 手动设置密码。

--client-id CLIENT_ID : 手动设置客户端 ID。

--device DEVICE : 手动指定要使用的串行端口/IP。例如 /dev/cu.SLAB_USBtoUART。 你也可以指定 OTA 以从 MQTT、DNS 或 mDNS 解析地址。 当存在多个选项时，这可以防止交互式提示。

可以指定多个 --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 进行配置。

--no-states / --states : 控制是否在日志输出中显示实体状态变化。默认情况下，使用原生 API 进行日志记录时，状态变化显示为 [S] 行（例如，[S][sensor]: 'Temperature' >> 22.5 °C）。 传递 --no-states 以抑制它们，仅查看固件日志消息，或传递 --states 以显示它们。

默认值可以通过环境变量 ESPHOME_LOG_STATES 设置：将其设置为 false 默认抑制状态变化，或设置为 true 以显示它们。--states 和 --no-states 标志始终优先于环境变量。

update-all 命令

esphome update-all <CONFIG>... 命令编译并通过 OTA 将所有固件上传到所有设备。 参数可以是 YAML 配置文件或包含配置文件的目录。对于找到的每个配置，它会运行 esphome run <CONFIG> --no-logs --device OTA，并在最后打印成功和失败的摘要。

使用 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 pr IPv6 address>

一些工作示例包括：

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 <your-api-key-from-yaml>

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

语法如下：

aioesphomeapi-discover

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

Status |Name |Address |MAC |Version |Platform |Board

参见

• 指南