命令行界面
ESPHome 的命令行界面始终具有以下格式
esphome [OPTIONS] <COMMAND> <CONFIGURATION...> [ARGUMENTS]NOTE
您可以在命令行界面中为某些命令指定多个配置文件，只需在 <COMMAND> 后列出所有文件：
esphome run livingroom.yaml kitchen.yaml--help 选项
Section titled “--help 选项”-h|--help
: 输出可能的 <commands> 和 [arguments]。
注意：您也可以对任何命令使用 --help 获取该命令特定的参数。
esphome <some_command> --help--verbose 选项
Section titled “--verbose 选项”-v|--verbose
: 启用详细 esphome 日志。
也可以通过环境变量 ESPHOME_VERBOSE=true 启用。
--quiet 选项
Section titled “--quiet 选项”-q|--quiet
: 禁用所有 esphome 日志。
--substitution 选项
Section titled “--substitution 选项”可以多次发出。
-s|--substitution KEY VALUE
: 定义或覆盖替换 KEY 为值 VALUE。
有关详情，请参阅命令行替换。
run 命令
Section titled “run 命令”esphome run <CONFIG> 命令是 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 设置。这可以在每个配置的 platformio 选项中覆盖，或在上传时使用此选项设置。
--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 命令
Section titled “config 命令”esphome config <CONFIG> 验证配置并显示验证结果。
compile 命令
Section titled “compile 命令”esphome compile <CONFIG> 验证配置并编译固件。
--only-generate
: 如果设置，仅生成 C++ 源代码，不编译固件。
upload 命令
Section titled “upload 命令”esphome upload <CONFIG> 验证配置并上传最近的固件构建。
--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 设置。这可以在每个配置的 platformio 选项中覆盖，或在上传时使用此选项设置。
--host-port HOST_PORT
: 指定用于旧版空中上传的主机端口。
clean-mqtt 命令
Section titled “clean-mqtt 命令”esphome clean-mqtt <CONFIG> 从 MQTT 代理清除保留的 MQTT 发现消息。请参阅与 Home Assistant MQTT 实体一起使用。
--topic TOPIC
: 手动设置从中清除保留消息的主题（默认为节点的 MQTT 发现主题）。
--username USERNAME
: 手动设置订阅的用户名。
--password PASSWORD
: 手动设置订阅的密码。
--client-id CLIENT_ID
: 手动设置订阅的客户端 ID。
wizard 命令
Section titled “wizard 命令”esphome wizard <CONFIG> 命令启动 ESPHome 配置创建向导。
mqtt-fingerprint 命令
Section titled “mqtt-fingerprint 命令”esphome mqtt-fingerprint <CONFIG> 命令显示用于 SSL MQTT 连接的远程 MQTT SSL 指纹。请参阅 SSL 指纹。
version 命令
Section titled “version 命令”esphome version 命令显示当前 ESPHome 版本并退出。
clean 命令
Section titled “clean 命令”esphome clean <CONFIG> 命令清除所有构建文件，可以帮助解决某些构建问题。
dashboard 命令
Section titled “dashboard 命令”esphome dashboard <CONFIG> 命令启动 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 时不起作用。
analyze-memory 命令
Section titled “analyze-memory 命令”NOTE
这是一个高级命令，主要供开发人员和调试内存问题使用。
esphome analyze-memory <CONFIG> 命令编译配置并按组件分析内存使用情况。
此命令适用于：
- 了解哪些组件消耗最多内存
- 识别优化机会以减少闪存或 RAM 使用
- 在向紧凑构建添加更多组件之前分析内存使用
- 调试接近内存限制的构建（特别是在 ESP8266 上）
- 为 ESPHome 开发和优化工作做出贡献
该命令在需要时自动编译配置（或如果源未更改则快速重新链接），然后分析生成的固件以显示按组件的内存使用详细分类，包括闪存（代码和数据）和 RAM 使用（数据和 BSS）。
logs 命令
Section titled “logs 命令”esphome logs <CONFIG> 命令验证配置并显示所有日志。
--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 自动补全
Section titled “使用 Bash 或 ZSH 自动补全”ESPHome 的命令行界面提供使用 Bash 或 ZSH 提供的自动补全功能的能力。
您可以通过将以下内容添加到您的 ~/.bashrc 文件来注册 ESPHome 进行自动补全：
eval "$(register-python-argcomplete esphome)"有关更多信息，请参阅 argcomplete 文档。
使用 ESPHome 提供的日志工具
Section titled “使用 ESPHome 提供的日志工具”ESPHome 提供两种类型的日志接口：API 和串行 (UART) 日志。
对于串行日志，有许多选项，包括 ESPHome Web 和 ESPHome CLI 的 run 命令。
对于基本的基于 API 的日志使用，可以使用 ESPHome 捆绑的 aioesphomeapi-logs 命令，
这对于位于远程/难以访问位置的 ESP 设备特别有用。
语法如下：
aioesphomeapi-logs <IPv4 或 IPv6 地址>一些有效的示例包括：
aioesphomeapi-logs 192.168.x.yaioesphomeapi-logs fe80::cdef:0123:4567:89abaioesphomeapi-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 设备的信息：
状态 |名称 |地址 |MAC |版本 |平台 |开发板