From cba34e770e8077f95305bdbbf5352def17d58dcf Mon Sep 17 00:00:00 2001
From: Tilman Vogel <tilman.vogel@web.de>
Date: Wed, 4 Mar 2026 03:18:36 +0100
Subject: [PATCH] [core] improve help text for --device option, mention `OTA`
 (#14445)

Co-authored-by: Jesse Hills <3060199+jesserockz@users.noreply.github.com>
---
 esphome/__main__.py | 7 ++++---
 esphome/const.py    | 3 +++
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/esphome/__main__.py b/esphome/__main__.py
index ffedb90bde..0164e2eeb3 100644
--- a/esphome/__main__.py
+++ b/esphome/__main__.py
@@ -23,6 +23,7 @@ import esphome.codegen as cg
 from esphome.config import iter_component_configs, read_config, strip_default_ids
 from esphome.const import (
     ALLOWED_NAME_CHARS,
+    ARGUMENT_HELP_DEVICE,
     CONF_API,
     CONF_BAUD_RATE,
     CONF_BROKER,
@@ -1367,7 +1368,7 @@ def parse_args(argv):
     parser_upload.add_argument(
         "--device",
         action="append",
-        help="Manually specify the serial port/address to use, for example /dev/ttyUSB0. Can be specified multiple times for fallback addresses.",
+        help=ARGUMENT_HELP_DEVICE,
     )
     parser_upload.add_argument(
         "--upload_speed",
@@ -1390,7 +1391,7 @@ def parse_args(argv):
     parser_logs.add_argument(
         "--device",
         action="append",
-        help="Manually specify the serial port/address to use, for example /dev/ttyUSB0. Can be specified multiple times for fallback addresses.",
+        help=ARGUMENT_HELP_DEVICE,
     )
     parser_logs.add_argument(
         "--reset",
@@ -1420,7 +1421,7 @@ def parse_args(argv):
     parser_run.add_argument(
         "--device",
         action="append",
-        help="Manually specify the serial port/address to use, for example /dev/ttyUSB0. Can be specified multiple times for fallback addresses.",
+        help=ARGUMENT_HELP_DEVICE,
     )
     parser_run.add_argument(
         "--upload_speed",
diff --git a/esphome/const.py b/esphome/const.py
index d5625f6a54..060e962573 100644
--- a/esphome/const.py
+++ b/esphome/const.py
@@ -11,6 +11,9 @@ VALID_SUBSTITUTIONS_CHARACTERS = (
     "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789_"
 )
 
+# CLI Help Text Constants
+ARGUMENT_HELP_DEVICE = "Manually specify the serial port/address to use, for example /dev/ttyUSB0. Can be specified multiple times for fallback addresses. Use 'OTA' for resolving from MQTT, DNS or mDNS and avoiding the interactive prompt."
+
 
 class Platform(StrEnum):
     """Platform identifiers for ESPHome."""