sonar v0.4.1 — CLI tool for inspecting and managing services listening on localhost ports

███████╗ ██████╗ ███╗   ██╗ █████╗ ██████╗
██╔════╝██╔═══██╗████╗  ██║██╔══██╗██╔══██╗
███████╗██║   ██║██╔██╗ ██║███████║██████╔╝
╚════██║██║   ██║██║╚██╗██║██╔══██║██╔══██╗
███████║╚██████╔╝██║ ╚████║██║  ██║██║  ██║
╚══════╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚═╝  ╚═╝

Wisse, was auf deinem Rechner läuft.

Ich hatte die Nase voll davon, jedes Mal lsof -iTCP -sTCP:LISTEN | grep ... auszuführen, wenn ein Port bereits belegt war, und dann noch eine Minute herauszufinden, ob es sich um einen Docker-Container oder einen verwaisten Dev-Server aus einem anderen Worktree handelte. Also habe ich sonar gebaut.

Es zeigt alles, was auf localhost lauscht, mit Docker-Containernamen, Compose-Projekten, Ressourcennutzung und anklickbaren URLs. Du kannst Prozesse beenden, Logs anzeigen, in Container einsteigen und mehr – alles über die Portnummer.

$ sonar list
PORT   PROCESS                      CONTAINER                    IMAGE             CPORT   URL
1780   proxy (traefik:3.0)          my-app-proxy-1               traefik:3.0       80      http://localhost:1780
3000   next-server (v16.1.6)                                                               http://localhost:3000
5432   db (postgres:17)             my-app-db-1                  postgres:17       5432    http://localhost:5432
6873   frontend (frontend:latest)   my-app-frontend-1            frontend:latest   5173    http://localhost:6873
9700   backend (backend:latest)     my-app-backend-1             backend:latest    8000    http://localhost:9700

5 Ports (4 Docker, 1 User)

Installation

Homebrew (macOS / Linux)

brew install raskrebs/sonar/sonar

Unter macOS wird dabei auch die Menüleisten-App sonar-tray installiert.

Installationsskript

curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | bash

Lädt die neueste Binärdatei nach ~/.local/bin herunter und fügt sie bei Bedarf zu deinem PATH hinzu. Starte dein Terminal neu oder führe source ~/.zshrc aus.

Unter Windows (PowerShell):

irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex

Benutzerdefinierter Installationsort:

curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | SONAR_INSTALL_DIR=/usr/local/bin bash

Installation einer bestimmten Version:

curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | SONAR_VERSION=vX.Y.Z bash

$env:SONAR_VERSION="vX.Y.Z"; irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex

Mit Go

go install github.com/raskrebs/sonar@latest

Hinweis: go install installiert nur die CLI. Die Menüleisten-Tray-App (sonar tray) ist ein natives Swift-Binary und muss separat gebaut werden – siehe Tray-App unten.

Shell-Komplettierungen (Tab-Vervollständigung für Portnummern):

sonar completion zsh > "${fpath[1]}/_sonar"   # zsh
sonar completion bash > /etc/bash_completion.d/sonar  # bash
sonar completion fish | source                 # fish

Verwendung

Ports auflisten

sonar list                     # alle Ports anzeigen
sonar list --stats             # inklusive CPU, Arbeitsspeicher, Zustand, Laufzeit
sonar list --filter docker     # nur Docker-Ports
sonar list --sort name         # nach Prozessname sortieren
sonar list --json              # JSON-Ausgabe
sonar list -a                  # Desktop-Apps einschließen
sonar list -c port,cpu,mem,uptime,state  # benutzerdefinierte Spalten
sonar list --health            # HTTP-Health-Checks ausführen
sonar list --host user@server  # entfernten Rechner via SSH scannen

Standardmäßig blendet sonar Desktop-Apps und Systemdienste aus, die auf TCP-Ports lauschen, aber für die Entwicklung nicht relevant sind – also Dinge wie Figma, Discord, Spotify, ControlCenter, AirPlay und andere macOS-.app-Bundles und /System/Library/-Daemons. Verwende -a, um sie einzuschließen.

Verfügbare Spalten: port, process, pid, type, url, cpu, mem, threads, uptime, state, connections, health, latency, container, image, containerport, compose, project, user, bind, ip

Einen Port inspizieren

sonar info 3000

Zeigt alles über einen Port: vollständigen Befehl, Benutzer, Bind-Addresse, CPU/Arbeitsspeicher/Threads, Laufzeit, Health-Check-Ergebnis und Docker-Details, falls zutreffend.

Prozesse beenden

sonar kill 3000                            # SIGTERM
sonar kill 3000 -f                         # SIGKILL
sonar kill-all --filter docker             # alle Docker-Container stoppen
sonar kill-all --project my-app            # ein Compose-Projekt stoppen
sonar kill-all --filter user -y            # Bestätigung überspringen

Docker-Container werden mit docker stop gestoppt, nicht durch Senden von Signalen.

Logs anzeigen

sonar logs 3000

Für Docker-Container führt es docker logs -f aus. Für native Prozesse findet es Logdateien via lsof und zeigt sie an. Fallback auf macOS log stream oder Linux /proc/<pid>/fd.

An einen Dienst anhängen

sonar attach 3000                          # Shell in Docker-Container oder TCP-Verbindung
sonar attach 3000 --shell bash             # bestimmte Shell

Auf Änderungen achten

sonar watch                                # alle 2s abfragen, Unterschiede anzeigen
sonar watch --stats                        # Live-Ressourcenstatistiken (wie docker stats)
sonar watch -i 500ms                       # schnellere Abfrage
sonar watch --notify                       # Desktop-Benachrichtigungen bei Port-Änderungen
sonar watch --host user@server             # entfernten Rechner überwachen

Abhängigkeitsgraph

sonar graph                                # anzeigen, welche Dienste miteinander kommunizieren
sonar graph --json                         # strukturierte Ausgabe
sonar graph --dot                          # Graphviz-DOT-Format

Zeigt etablierte Verbindungen zwischen lauschenden Ports (z. B. dein Backend, das sich mit Postgres verbindet).

Profile

Speichere eine Reihe erwarteter Ports für ein Projekt und prüfe dann, ob alle laufen, oder fahre sie herunter:

sonar profile create my-app                # aktuellen Port-Snapshot erstellen
sonar profile list                         # gespeicherte Profile anzeigen
sonar profile show my-app                  # Profildetails anzeigen
sonar up my-app                            # prüfen, welche erwarteten Ports laufen
sonar down my-app                          # alle Ports im Profil stoppen

Auf Ports warten

sonar wait 5432                        # blockieren, bis Port Verbindungen akzeptiert
sonar wait 5432 3000 6379              # auf mehrere Ports warten
sonar wait 5432 --timeout 30s          # nach 30 Sekunden fehlschlagen
sonar wait 5432 --http                 # auf HTTP 200 warten, nicht nur TCP offen
sonar wait 5432 --http=/health         # bestimmten Endpunkt prüfen
sonar wait 5432 -i 500ms               # benutzerdefiniertes Abfrageintervall
sonar wait 5432 -q                     # keine Ausgabe, nur Exit-Code (für Skripte)

Nützlich für Skripte rund um docker compose up -d oder Hintergrunddienste. Das --http-Flag wartet auf eine tatsächliche HTTP-200-399-Antwort, nicht nur auf einen TCP-Socket, was Dienste abfängt, die Verbindungen annehmen, bevor sie wirklich bereit sind. Verwende --http=/health, um einen bestimmten Endpunkt zu prüfen. Exit-Codes: 0 (bereit), 1 (Timeout), 2 (unterbrochen).

docker compose up -d
sonar wait 5432 3000 --timeout 60s && npm run migrate && npm run test

Port-Weiterleitung

sonar map 6873 3002

Leitet Datenverkehr weiter, sodass der Dienst auf Port 6873 auch auf Port 3002 verfügbar ist.

Freie Ports finden

sonar next                                 # erster freier Port ab 3000
sonar next 8000                            # erster freier Port ab 8000
sonar next 3000-3100                       # erster freier Port im Bereich
sonar next -n 3                            # 3 aufeinander folgende freie Ports
sonar next --json                          # JSON-Ausgabe

Sonstiges

sonar open 3000                            # im Browser öffnen
sonar tray                                 # Menüleisten-App mit Live-Statistiken (macOS)
sonar --no-color                           # Farben deaktivieren (respektiert auch NO_COLOR-Umgebungsvariable)

Das --stats-Flag holt prozess- und containerbezogene Ressourcennutzung. Für Docker-Container verwendet es die Docker-Engine-API für genaue Metriken pro Container. Ohne --stats gibt sonar sofort Ergebnisse zurück.

Konfiguration

sonar liest optionale Standardwerte aus ~/.config/sonar/config.yaml. Die Datei ist optional – ohne sie gelten integrierte Standardwerte. Befehlszeilenflags überschreiben die Konfigurationsdatei immer.

Erstelle eine Startdatei:

sonar config init       # kommentierte Vorlage schreiben
sonar config path       # Dateipfad ausgeben
sonar config edit       # in $EDITOR öffnen

Beispielkonfiguration:

list:
  columns: [port, process, container, image, containerport, url]
  sort: port            # port | pid | name | type
  filter: ""            # docker | user | system | "" (alle)
  all: false            # Desktop-Apps standardmäßig einschließen
color: true             # auf false setzen, um Farbausgabe zu deaktivieren
services:               # benutzerdefinierte/unbekannte Ports beschriften
  9000: php-fpm
  5050: my-dashboard

Ungültige Werte werden mit einer Warnung ignoriert; sonar fährt mit den Standardwerten fort.

Tray-App

Die Menüleisten-Tray-App (nur macOS) ist ein natives Swift-Binary, das Live-Port-Statistiken in deiner Menüleiste anzeigt. Wenn du sonar über das Installationsskript oder eine GitHub-Release installiert hast, ist das Tray-Binary (sonar-tray) automatisch enthalten.

Wenn du über go install installiert hast, baue es manuell:

swiftc -O -o sonar-tray tray/SonarTray.swift -target arm64-apple-macos13

Verschiebe dann sonar-tray an einen Ort in deinem $PATH und führe aus:

sonar tray

Unterstützte Plattformen

macOS (verwendet lsof)
Linux (verwendet ss)
Windows (verwendet netstat)

Mitwirkende

Danke an alle, die zu sonar beigetragen haben!