KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #dsh-plugin #ai-agent #developer-tools #codex #typescript #cli #deepseek-harness #claude-code #ai-agents #mcp #rust

sonar

★ 1,090 Open GitHub ↗

CLI tool for inspecting and managing services listening on localhost ports

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

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

Know what's running on your machine.

</div>

I got tired of running `lsof -iTCP -sTCP:LISTEN | grep ...` every time a port was already taken, then spending another minute figuring out if it was a Docker container or some orphaned dev server from another worktree. So I built sonar.

It shows everything listening on localhost, with Docker container names, Compose projects, resource usage, and clickable URLs. You can kill processes, tail logs, shell into containers, and more — all by port number.

```
$ 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)
```

## Install

### Homebrew (macOS / Linux)

```sh
brew install raskrebs/sonar/sonar
```

On macOS this also installs the `sonar-tray` menu bar app.

### Install script

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

Downloads the latest binary to `~/.local/bin` and adds it to your PATH if needed. Restart your terminal or `source ~/.zshrc`.

On Windows (PowerShell):

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

Custom install location:

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

Install a specific version:

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

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

### Using Go

```sh
go install github.com/raskrebs/sonar@latest
```

> **Note:** `go install` only installs the CLI. The menu bar tray app (`sonar tray`) is a native Swift binary and must be built separately — see [Tray app](#tray-app) below.

Shell completions (tab-complete port numbers):

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

## Usage

### List ports

```sh
sonar list                     # show all ports
sonar list --stats             # include CPU, memory, state, uptime
sonar list --filter docker     # only Docker ports
sonar list --sort name         # sort by process name
sonar list --json              # JSON output
sonar list -a                  # include desktop apps
sonar list -c port,cpu,mem,uptime,state  # custom columns
sonar list --health            # run HTTP health checks
sonar list --host user@server  # scan a remote machine via SSH
```

By default, sonar hides desktop apps and system services that listen on TCP ports but aren't relevant to development — things like Figma, Discord, Spotify, ControlCenter, AirPlay, and other macOS `.app` bundles and `/System/Library/` daemons. Use `-a` to include them.

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

### Inspect a port

```sh
sonar info 3000
```

Shows everything about a port: full command, user, bind address, CPU/memory/threads, uptime, health check result, and Docker details if applicable.

### Kill processes

```sh
sonar kill 3000                            # SIGTERM
sonar kill 3000 -f                         # SIGKILL
sonar kill-all --filter docker             # stop all Docker containers
sonar kill-all --project my-app            # stop a Compose project
sonar kill-all --filter user -y            # skip confirmation
```

Docker containers are stopped with `docker stop` instead of sending signals.

### View logs

```sh
sonar logs 3000
```

For Docker containers, runs `docker logs -f`. For native processes, discovers log files via `lsof` and tails them. Falls back to macOS `log stream` or Linux `/proc/<pid>/fd`.

### Attach to a service

```sh
sonar attach 3000                          # shell into Docker container, or TCP connect
sonar attach 3000 --shell bash             # specific shell
```

### Watch for changes

```sh
sonar watch                                # poll every 2s, show diffs
sonar watch --stats                        # live resource stats (like docker stats)
sonar watch -i 500ms                       # faster polling
sonar watch --notify                       # desktop notifications when ports go up/down
sonar watch --host user@server             # watch a remote machine
```

### Dependency graph

```sh
sonar graph                                # show which services talk to each other
sonar graph --json                         # structured output
sonar graph --dot                          # Graphviz DOT format
```

Shows established connections between listening ports (e.g. your backend connecting to postgres).

### Profiles

Save a set of expected ports for a project, then check if they're all up or tear them down:

```sh
sonar profile create my-app                # snapshot current ports
sonar profile list                         # list saved profiles
sonar profile show my-app                  # show profile details
sonar up my-app                            # check which expected ports are running
sonar down my-app                          # stop all ports in the profile
```

### Wait for ports

```sh
sonar wait 5432                        # block until port is accepting connections
sonar wait 5432 3000 6379              # wait for multiple ports
sonar wait 5432 --timeout 30s         # fail after 30 seconds
sonar wait 5432 --http                # wait for HTTP 200, not just TCP open
sonar wait 5432 --http=/health        # check a specific endpoint
sonar wait 5432 -i 500ms              # custom polling interval
sonar wait 5432 -q                    # no output, just exit code (for scripts)
```

Useful for scripting around `docker compose up -d` or background services. The `--http` flag waits for an actual HTTP 200-399 response, not just a TCP socket, which catches services that accept connections before they're truly ready. Use `--http=/health` to check a specific endpoint. Exit codes: `0` (ready), `1` (timeout), `2` (interrupted).

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

### Port mapping

```sh
sonar map 6873 3002
```

Proxies traffic so the service on port 6873 is also available on port 3002.

### Find free ports

```sh
sonar next                                 # first next free port from 3000
sonar next 8000                            # first next free port from 8000
sonar next 3000-3100                       # first next free port in range
sonar next -n 3                            # 3 consecutive free ports
sonar next --json                          # JSON output
```

### Other

```sh
sonar open 3000                            # open in browser
sonar tray                                 # menu bar app with live stats (macOS)
sonar --no-color                           # disable colors (also respects NO_COLOR env)
```

The `--stats` flag fetches per-process and per-container resource usage. For Docker containers, it uses the Docker Engine API for accurate per-container metrics. Without `--stats`, sonar returns instantly.

## Configuration

`sonar` reads optional defaults from `~/.config/sonar/config.yaml`. The file is
optional — without it, built-in defaults apply. Command-line flags always
override the config file.

Create a starter file:

```bash
sonar config init       # write a commented template
sonar config path       # print the file location
sonar config edit       # open it in $EDITOR
```

Example config:

```yaml
list:
  columns: [port, process, container, image, containerport, url]
  sort: port            # port | pid | name | type
  filter: ""            # docker | user | system | "" (all)
  all: false            # include desktop apps by default
color: true             # set false to disable colored output
services:               # label custom/unknown ports
  9000: php-fpm
  5050: my-dashboard
```

Invalid values are ignored with a warning; sonar continues with defaults.

## Tray app

The menu bar tray app (macOS only) is a native Swift binary that shows live port stats in your menu bar. If you installed sonar via the install script or a GitHub release, the tray binary (`sonar-tray`) is included automatically.

If you installed via `go install`, build it manually:

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

Then move `sonar-tray` somewhere on your `$PATH` and run:

```sh
sonar tray
```

## Supported platforms

- macOS (uses `lsof`)
- Linux (uses `ss`)
- Windows (uses `netstat`)

## Contributors

Thanks to everyone who has contributed to sonar!

sonar

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README