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

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

Sachez ce qui tourne sur votre machine.

J'en ai eu marre de lancer lsof -iTCP -sTCP:LISTEN | grep ... à chaque fois qu'un port était déjà pris, puis de perdre une minute à déterminer s'il s'agissait d'un conteneur Docker ou d'un serveur de développement orphelin d'un autre espace de travail. Alors j'ai construit sonar.

Il affiche tout ce qui écoute sur localhost, avec les noms des conteneurs Docker, les projets Compose, l'utilisation des ressources et des URL cliquables. Vous pouvez tuer des processus, suivre les logs, ouvrir un shell dans les conteneurs, et plus encore — le tout par numéro de port.

$ 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

Sur macOS, cela installe également l'application de la barre de menus sonar-tray.

Script d'installation

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

Télécharge le dernier binaire dans ~/.local/bin et l'ajoute à votre PATH si nécessaire. Redémarrez votre terminal ou exécutez source ~/.zshrc.

Sous Windows (PowerShell) :

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

Emplacement d'installation personnalisé :

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

Installer une version spécifique :

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

Avec Go

go install github.com/raskrebs/sonar@latest

Remarque : go install installe uniquement le CLI. L'application de la barre de menus (sonar tray) est un binaire Swift natif et doit être compilée séparément — voir Application de la barre de menus ci-dessous.

Complétions shell (auto-complétion des numéros de port) :

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

Utilisation

Lister les ports

sonar list                     # afficher tous les ports
sonar list --stats             # inclure CPU, mémoire, état, durée de fonctionnement
sonar list --filter docker     # uniquement les ports Docker
sonar list --sort name         # trier par nom de processus
sonar list --json              # sortie JSON
sonar list -a                  # inclure les applications de bureau
sonar list -c port,cpu,mem,uptime,state  # colonnes personnalisées
sonar list --health            # effectuer des vérifications de santé HTTP
sonar list --host user@server  # scanner une machine distante via SSH

Par défaut, sonar masque les applications de bureau et les services système qui écoutent sur des ports TCP mais ne sont pas pertinents pour le développement — par exemple Figma, Discord, Spotify, ControlCenter, AirPlay et autres bundles .app macOS et démons /System/Library/. Utilisez -a pour les inclure.

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

Inspecter un port

sonar info 3000

Affiche tout ce qui concerne un port : commande complète, utilisateur, adresse de liaison, CPU/mémoire/threads, durée de fonctionnement, résultat de la vérification de santé et détails Docker le cas échéant.

Tuer des processus

sonar kill 3000                            # SIGTERM
sonar kill 3000 -f                         # SIGKILL
sonar kill-all --filter docker             # arrêter tous les conteneurs Docker
sonar kill-all --project my-app            # arrêter un projet Compose
sonar kill-all --filter user -y            # ignorer la confirmation

Les conteneurs Docker sont arrêtés avec docker stop au lieu d'envoyer des signaux.

Voir les logs

sonar logs 3000

Pour les conteneurs Docker, exécute docker logs -f. Pour les processus natifs, découvre les fichiers de log via lsof et les suit. Repli sur macOS log stream ou Linux /proc/<pid>/fd.

Se connecter à un service

sonar attach 3000                          # ouvrir un shell dans le conteneur Docker, ou connexion TCP
sonar attach 3000 --shell bash             # shell spécifique

Surveiller les changements

sonar watch                                # interroger toutes les 2s, afficher les différences
sonar watch --stats                        # statistiques en direct (comme docker stats)
sonar watch -i 500ms                       # interrogation plus rapide
sonar watch --notify                       # notifications de bureau quand des ports apparaissent/disparaissent
sonar watch --host user@server             # surveiller une machine distante

Graphe des dépendances

sonar graph                                # montrer quels services communiquent entre eux
sonar graph --json                         # sortie structurée
sonar graph --dot                          # format Graphviz DOT

Affiche les connexions établies entre les ports d'écoute (par exemple, votre backend se connectant à postgres).

Profils

Enregistrez un ensemble de ports attendus pour un projet, puis vérifiez s'ils sont tous actifs ou arrêtez-les :

sonar profile create my-app                # instantané des ports actuels
sonar profile list                         # lister les profils sauvegardés
sonar profile show my-app                  # afficher les détails du profil
sonar up my-app                            # vérifier quels ports attendus sont en cours d'exécution
sonar down my-app                          # arrêter tous les ports du profil

Attendre des ports

sonar wait 5432                        # bloquer jusqu'à ce que le port accepte des connexions
sonar wait 5432 3000 6379              # attendre plusieurs ports
sonar wait 5432 --timeout 30s         # échouer après 30 secondes
sonar wait 5432 --http                # attendre une réponse HTTP 200, pas seulement une ouverture TCP
sonar wait 5432 --http=/health        # vérifier un point d'accès spécifique
sonar wait 5432 -i 500ms              # intervalle d'interrogation personnalisé
sonar wait 5432 -q                    # pas de sortie, seulement le code de sortie (pour les scripts)

Utile pour le script autour de docker compose up -d ou des services en arrière-plan. L'option --http attend une réponse HTTP 200-399 réelle, pas seulement une socket TCP, ce qui permet de détecter les services qui acceptent des connexions avant d'être réellement prêts. Utilisez --http=/health pour vérifier un point d'accès spécifique. Codes de sortie : 0 (prêt), 1 (délai expiré), 2 (interrompu).

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

Mappage de ports

sonar map 6873 3002

Proxifie le trafic pour que le service sur le port 6873 soit également disponible sur le port 3002.

Trouver des ports libres

sonar next                                 # premier port libre à partir de 3000
sonar next 8000                            # premier port libre à partir de 8000
sonar next 3000-3100                       # premier port libre dans la plage
sonar next -n 3                            # 3 ports libres consécutifs
sonar next --json                          # sortie JSON

Autres

sonar open 3000                            # ouvrir dans le navigateur
sonar tray                                 # application de la barre de menus avec statistiques en direct (macOS)
sonar --no-color                           # désactiver les couleurs (respecte aussi la variable d'environnement NO_COLOR)

L'option --stats récupère l'utilisation des ressources par processus et par conteneur. Pour les conteneurs Docker, elle utilise l'API du moteur Docker pour des métriques précises par conteneur. Sans --stats, sonar répond instantanément.

Configuration

sonar lit des paramètres par défaut facultatifs dans ~/.config/sonar/config.yaml. Ce fichier est facultatif — sans lui, les paramètres par défaut intégrés s'appliquent. Les options en ligne de commande remplacent toujours le fichier de configuration.

Créez un fichier de démarrage :

sonar config init       # écrire un modèle commenté
sonar config path       # afficher l'emplacement du fichier
sonar config edit       # l'ouvrir dans $EDITOR

Exemple de configuration :

list:
  columns: [port, process, container, image, containerport, url]
  sort: port            # port | pid | name | type
  filter: ""            # docker | user | system | "" (tout)
  all: false            # inclure les applications de bureau par défaut
color: true             # mettre false pour désactiver la sortie colorée
services:               # étiqueter les ports personnalisés/inconnus
  9000: php-fpm
  5050: my-dashboard

Les valeurs invalides sont ignorées avec un avertissement ; sonar continue avec les valeurs par défaut.

Application de la barre de menus

L'application de la barre de menus (macOS uniquement) est un binaire Swift natif qui affiche les statistiques des ports en direct dans votre barre de menus. Si vous avez installé sonar via le script d'installation ou une version GitHub, le binaire de la barre de menus (sonar-tray) est inclus automatiquement.

Si vous avez installé via go install, compilez-le manuellement :

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

Ensuite, déplacez sonar-tray quelque part dans votre $PATH et exécutez :

sonar tray

Plates-formes supportées

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

Contributeurs

Merci à tous ceux qui ont contribué à sonar !

Lire plus