From d8932820fa8ed916789dfbc04ea6ffed6b32f7da Mon Sep 17 00:00:00 2001
From: Fabiana Cecin <fabiana@waku.org>
Date: Mon, 20 Apr 2026 14:45:28 -0300
Subject: [PATCH] Fixes from Ivan's review

* Document actual env var names in config help messages
* Add port value resolution order to README.md
---
 README.md                    |  7 +++++--
 tools/confutils/cli_args.nim | 22 ++++++++++++++++------
 2 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/README.md b/README.md
index 37400fe13..577a3a001 100644
--- a/README.md
+++ b/README.md
@@ -160,8 +160,11 @@ and any supplied configuration for that port.
 | `--metrics-server-port` | `LOGOS_DELIVERY_METRICS_PORT`    |
 | `--websocket-port`      | `LOGOS_DELIVERY_WEBSOCKET_PORT`  |
 
-The override just replaces the configured port value, so any subsequent transform
-such as `--ports-shift` still applies on top.
+Effective port is determined in this order:
+
+1. Config parameter (CLI flag or library API)
+2. Environment variable
+3. Any post-processing (e.g. `--ports-shift`)
 
 ## Formatting
 
diff --git a/tools/confutils/cli_args.nim b/tools/confutils/cli_args.nim
index d63b5880c..367feb02b 100644
--- a/tools/confutils/cli_args.nim
+++ b/tools/confutils/cli_args.nim
@@ -192,8 +192,11 @@ type WakuNodeConf* = object
       name: "listen-address"
     .}: IpAddress
 
-    tcpPort* {.desc: "TCP listening port.", defaultValue: 60000, name: "tcp-port".}:
-      Port
+    tcpPort* {.
+      desc: "TCP listening port. (env var override: " & EnvP2pTcpPort & ")",
+      defaultValue: 60000,
+      name: "tcp-port"
+    .}: Port
 
     portsShift* {.
       desc: "Add a shift to all port numbers.", defaultValue: 0, name: "ports-shift"
@@ -489,7 +492,8 @@ with the drawback of consuming some more bandwidth.""",
     .}: IpAddress
 
     restPort* {.
-      desc: "Listening port of the REST HTTP server.",
+      desc:
+        "Listening port of the REST HTTP server. (env var override: " & EnvRestPort & ")",
       defaultValue: 8645,
       name: "rest-port"
     .}: uint16
@@ -530,7 +534,9 @@ with the drawback of consuming some more bandwidth.""",
     .}: IpAddress
 
     metricsServerPort* {.
-      desc: "Listening HTTP port of the metrics server.",
+      desc:
+        "Listening HTTP port of the metrics server. (env var override: " & EnvMetricsPort &
+        ")",
       defaultValue: 8008,
       name: "metrics-server-port"
     .}: uint16
@@ -564,7 +570,9 @@ with the drawback of consuming some more bandwidth.""",
     .}: Option[bool]
 
     discv5UdpPort* {.
-      desc: "Listening UDP port for Node Discovery v5.",
+      desc:
+        "Listening UDP port for Node Discovery v5. (env var override: " &
+        EnvDiscv5UdpPort & ")",
       defaultValue: 9000,
       name: "discv5-udp-port"
     .}: Port
@@ -664,7 +672,9 @@ with the drawback of consuming some more bandwidth.""",
     .}: bool
 
     websocketPort* {.
-      desc: "WebSocket listening port.", defaultValue: 8000, name: "websocket-port"
+      desc: "WebSocket listening port. (env var override: " & EnvWebSocketPort & ")",
+      defaultValue: 8000,
+      name: "websocket-port"
     .}: Port
 
     websocketSecureSupport* {.