From 3c439ec6812d766bf94b61188e234fb640caa889 Mon Sep 17 00:00:00 2001
From: Byrn Tong <26782336+cixuuz@users.noreply.github.com>
Date: Sun, 3 May 2026 08:10:28 +0000
Subject: [PATCH] feat(gateway): add `hermes gateway list` to show all
 profiles' gateway status
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add a new `hermes gateway list` subcommand that shows the running
status of gateways across all profiles in a single view:

    Gateways:
      ✓ default (current)        — PID 155469
      ✓ wx1                      — PID 166893
      ✗ dev                      — not running

Also includes `_print_other_profiles_gateway_status()` which appends
an "Other profiles" section to `hermes gateway status` output when
other profile gateways are running.

Both use existing `list_profiles()` and `find_profile_gateway_processes()`
— no new dependencies.

Closes #19127
Related: #19113, #4402, #4587
---
 hermes_cli/gateway.py | 43 +++++++++++++++++++++++++++++++++++++++++++
 hermes_cli/main.py    |  3 +++
 2 files changed, 46 insertions(+)

diff --git a/hermes_cli/gateway.py b/hermes_cli/gateway.py
index c751ced8ae..9dc34b9d78 100644
--- a/hermes_cli/gateway.py
+++ b/hermes_cli/gateway.py
@@ -830,6 +830,46 @@ def _print_other_profiles_gateway_status() -> None:
         pass
 
 
+def _gateway_list() -> None:
+    """List all profiles and their gateway running status.
+
+    Provides a single-command overview of every known profile and whether
+    its gateway is currently running, so multi-profile users don't have to
+    check each profile individually.
+    """
+    try:
+        from hermes_cli.profiles import list_profiles, get_active_profile_name
+    except Exception:
+        print("Unable to list profiles.")
+        return
+
+    profiles = list_profiles()
+    if not profiles:
+        print("No profiles found.")
+        return
+
+    current = get_active_profile_name()
+
+    print("Gateways:")
+    for prof in profiles:
+        marker = "✓" if prof.gateway_running else "✗"
+        label = prof.name
+        if prof.name == current:
+            label += " (current)"
+        parts = [f"  {marker} {label:<24s}"]
+        if prof.gateway_running:
+            try:
+                from gateway.status import get_running_pid
+                pid = get_running_pid(prof.path / "gateway.pid", cleanup_stale=False)
+                if pid:
+                    parts.append(f"PID {pid}")
+            except Exception:
+                pass
+        else:
+            parts.append("not running")
+        print(" — ".join(parts))
+
+
 def kill_gateway_processes(force: bool = False, exclude_pids: set | None = None,
                            all_profiles: bool = False) -> int:
     """Kill any running gateway processes. Returns count killed.
@@ -4798,6 +4838,9 @@ def _gateway_command_inner(args):
         # Show other profiles' gateway status for multi-profile awareness
         _print_other_profiles_gateway_status()
 
+    elif subcmd == "list":
+        _gateway_list()
+
     elif subcmd == "migrate-legacy":
         # Stop, disable, and remove legacy Hermes gateway unit files from
         # pre-rename installs (e.g. hermes.service). Profile units and
diff --git a/hermes_cli/main.py b/hermes_cli/main.py
index 15bf312e0a..1f0ea8dd1d 100644
--- a/hermes_cli/main.py
+++ b/hermes_cli/main.py
@@ -8690,6 +8690,9 @@ def main():
         help="Target the Linux system-level gateway service",
     )
 
+    # gateway list
+    gateway_subparsers.add_parser("list", help="List all profiles and their gateway status")
+
     # gateway setup
     gateway_subparsers.add_parser("setup", help="Configure messaging platforms")