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

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

Scopri cosa c'è in esecuzione sulla tua macchina.

Mi sono stancato di eseguire lsof -iTCP -sTCP:LISTEN | grep ... ogni volta che una porta era già occupata, per poi perdere un altro minuto a capire se si trattava di un container Docker o di qualche server di sviluppo orfano da un altro worktree. Così ho creato sonar.

Mostra tutto ciò che è in ascolto su localhost, con i nomi dei container Docker, i progetti Compose, l'utilizzo delle risorse e URL cliccabili. Puoi terminare processi, seguire i log, accedere ai container e molto altro — tutto tramite numero di porta.

$ sonar list
PORTA   PROCESSO                      CONTENITORE                    IMMAGINE        P_CONTAINER   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 porte (4 docker, 1 utente)

Installazione

Homebrew (macOS / Linux)

brew install raskrebs/sonar/sonar

Su macOS questo installa anche l'app della barra dei menu sonar-tray.

Script di installazione

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

Scarica l'ultimo binario in ~/.local/bin e lo aggiunge al tuo PATH se necessario. Riavvia il terminale o esegui source ~/.zshrc.

Su Windows (PowerShell):

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

Posizione di installazione personalizzata:

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

Installa una versione specifica:

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

Usando Go

go install github.com/raskrebs/sonar@latest

Nota: go install installa solo la CLI. L'app della barra dei menu (sonar tray) è un binario Swift nativo e deve essere compilata separatamente — vedi App della barra dei menu più sotto.

Completamenti per la shell (completamento tab dei numeri di porta):

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

Utilizzo

Elenca le porte

sonar list                     # mostra tutte le porte
sonar list --stats             # include CPU, memoria, stato, uptime
sonar list --filter docker     # solo porte Docker
sonar list --sort name         # ordina per nome del processo
sonar list --json              # output JSON
sonar list -a                  # include app desktop
sonar list -c port,cpu,mem,uptime,state  # colonne personalizzate
sonar list --health            # esegue controlli di integrità HTTP
sonar list --host user@server  # esamina una macchina remota via SSH

Per impostazione predefinita, sonar nasconde le app desktop e i servizi di sistema che ascoltano su porte TCP ma non sono rilevanti per lo sviluppo — cose come Figma, Discord, Spotify, ControlCenter, AirPlay e altri bundle .app di macOS e demoni di /System/Library/. Usa -a per includerli.

Colonne disponibili: port, process, pid, type, url, cpu, mem, threads, uptime, state, connections, health, latency, container, image, containerport, compose, project, user, bind, ip

Ispeziona una porta

sonar info 3000

Mostra tutto su una porta: comando completo, utente, indirizzo di bind, CPU/memoria/thread, uptime, risultato del controllo di integrità e dettagli Docker se applicabili.

Termina i processi

sonar kill 3000                            # SIGTERM
sonar kill 3000 -f                         # SIGKILL
sonar kill-all --filter docker             # ferma tutti i container Docker
sonar kill-all --project my-app            # ferma un progetto Compose
sonar kill-all --filter user -y            # salta la conferma

I container Docker vengono arrestati con docker stop invece di inviare segnali.

Visualizza i log

sonar logs 3000

Per i container Docker, esegue docker logs -f. Per i processi nativi, scopre i file di log tramite lsof e li segue. In alternativa usa log stream su macOS o /proc/<pid>/fd su Linux.

Collega a un servizio

sonar attach 3000                          # shell nel container Docker, o connessione TCP
sonar attach 3000 --shell bash             # shell specifica

Monitora le modifiche

sonar watch                                # polling ogni 2s, mostra le differenze
sonar watch --stats                        # statistiche delle risorse in tempo reale (come docker stats)
sonar watch -i 500ms                       # polling più veloce
sonar watch --notify                       # notifiche desktop quando le porte vanno su/giù
sonar watch --host user@server             # monitora una macchina remota

Grafico delle dipendenze

sonar graph                                # mostra quali servizi comunicano tra loro
sonar graph --json                         # output strutturato
sonar graph --dot                          # formato Graphviz DOT

Mostra le connessioni stabilite tra le porte in ascolto (es. il tuo backend che si connette a postgres).

Profili

Salva un insieme di porte previste per un progetto, poi verifica se sono tutte attive o fermale:

sonar profile create my-app                # istantanea delle porte correnti
sonar profile list                         # elenca i profili salvati
sonar profile show my-app                  # mostra i dettagli del profilo
sonar up my-app                            # verifica quali porte previste sono in esecuzione
sonar down my-app                          # ferma tutte le porte nel profilo

Attesa delle porte

sonar wait 5432                        # blocca finché la porta non accetta connessioni
sonar wait 5432 3000 6379              # attesa per più porte
sonar wait 5432 --timeout 30s         # fallisce dopo 30 secondi
sonar wait 5432 --http                # attesa per HTTP 200, non solo TCP aperto
sonar wait 5432 --http=/health        # controlla un endpoint specifico
sonar wait 5432 -i 500ms              # intervallo di polling personalizzato
sonar wait 5432 -q                    # nessun output, solo codice di uscita (per script)

Utile per script attorno a docker compose up -d o servizi in background. Il flag --http attende una risposta HTTP 200-399 effettiva, non solo un socket TCP, catturando servizi che accettano connessioni prima di essere realmente pronti. Usa --http=/health per controllare un endpoint specifico. Codici di uscita: 0 (pronto), 1 (timeout), 2 (interrotto).

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

Mappatura delle porte

sonar map 6873 3002

Proxy del traffico in modo che il servizio sulla porta 6873 sia disponibile anche sulla porta 3002.

Trova porte libere

sonar next                                 # prima porta libera successiva da 3000
sonar next 8000                            # prima porta libera successiva da 8000
sonar next 3000-3100                       # prima porta libera successiva nell'intervallo
sonar next -n 3                            # 3 porte libere consecutive
sonar next --json                          # output JSON

Altro

sonar open 3000                            # apre nel browser
sonar tray                                 # app nella barra dei menu con statistiche in tempo reale (macOS)
sonar --no-color                           # disabilita i colori (rispetta anche la variabile d'ambiente NO_COLOR)

Il flag --stats recupera l'utilizzo delle risorse per processo e per container. Per i container Docker, utilizza l'API Docker Engine per metriche accurate per container. Senza --stats, sonar restituisce immediatamente.

Configurazione

sonar legge le impostazioni predefinite opzionali da ~/.config/sonar/config.yaml. Il file è opzionale — senza di esso, vengono applicate le impostazioni predefinite interne. I flag della riga di comando sovrascrivono sempre il file di configurazione.

Crea un file iniziale:

sonar config init       # scrive un template commentato
sonar config path       # stampa la posizione del file
sonar config edit       # lo apre in $EDITOR

Esempio di configurazione:

list:
  columns: [port, process, container, image, containerport, url]
  sort: port            # port | pid | name | type
  filter: ""            # docker | user | system | "" (tutti)
  all: false            # include le app desktop per default
color: true             # imposta false per disabilitare l'output a colori
services:               # etichetta porte personalizzate/sconosciute
  9000: php-fpm
  5050: my-dashboard

I valori non validi vengono ignorati con un avviso; sonar continua con i valori predefiniti.

L'app della barra dei menu (solo macOS) è un binario Swift nativo che mostra le statistiche delle porte in tempo reale nella barra dei menu. Se hai installato sonar tramite lo script di installazione o una release di GitHub, il binario della barra (sonar-tray) è incluso automaticamente.

Se hai installato tramite go install, compilalo manualmente:

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

Quindi sposta sonar-tray da qualche parte nel tuo $PATH ed esegui:

sonar tray

Piattaforme supportate

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

Contributori

Grazie a tutti coloro che hanno contribuito a sonar!