
Инструмент командной строки для проверки и управления службами, прослушивающими порты localhost
<div align="center">
```
██████ ███ ██████ ██ ██████
██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ████
██ ██ ██ ██ ██ ██ ██ ██
██████ ███ ██ ██ ██ ██ ██ ██
```
Знайте, что работает на вашей машине.
</div>
Sonar показывает всё, что слушает на localhost, и приводит это в порядок: каждый порт
принадлежит **группе** — обычно это репозиторий, из которого он был запущен, — а
внутри этой группы именованному **сервису**. Запускайте свои dev-серверы с помощью
`sonar start`, и весь проект становится одной сущностью, которую можно вывести в виде дерева,
дождаться, отслеживать и остановить одной командой. Docker-контейнеры, проекты Compose
и процессы, запущенные вручную, тоже подхватываются, без какой-либо
конфигурации.
```
$ sonar list --tree
my-app (3 ports, running) ~/code/my-app
├─ 5432 db postgres:17 http://localhost:5432
├─ 5173 frontend vite (v5.4) http://localhost:5173
└─ 8000 api uvicorn app:app http://localhost:8000
ungrouped (1 port)
└─ 3000 next-server (v16.1.6) http://localhost:3000
```
## Установка
### Homebrew (macOS / Linux)
```sh
brew install raskrebs/sonar/sonar
```
Homebrew 6 отказывается загружать формулы из сторонних tap-репозиториев, пока вы один раз не подтвердите доверие к tap
(`Error: Refusing to load formula raskrebs/sonar/sonar from untrusted tap`):
```sh
brew trust raskrebs/sonar
```
### Скрипт установки
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | bash
```
Загружает последний бинарный файл в `~/.local/bin` и добавляет его в ваш PATH при необходимости. Перезапустите терминал или выполните `source ~/.zshrc`.
В Windows (PowerShell):
```powershell
irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex
```
Пользовательское расположение установки:
```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | SONAR_INSTALL_DIR=/usr/local/bin bash
```
Установите конкретную версию:
```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
```
### Использование Go
```sh
go install github.com/raskrebs/sonar@latest
```
Завершения оболочки (автодополнение номеров портов по Tab):
```sh
sonar completion zsh > "${fpath[1]}/_sonar" # zsh
sonar completion bash > /etc/bash_completion.d/sonar # bash
sonar completion fish | source # fish
```
## Шестьдесят секунд
Опишите, как запускается ваш проект, в файле `sonar.yaml` в корне репозитория,
вместо `dev.sh`:
```yaml
name: my-app
services:
- name: db
cmd: docker compose up db
port: 5432
- name: api
cmd: uv run uvicorn app:app --port ${port}
port: auto
depends_on: [db]
- name: frontend
cmd: npm run dev -- --port ${port} --strictPort
port: auto
depends_on: [api]
env:
VITE_API_URL: ${api.url}
```
Затем запустите его:
```sh
sonar start
```
```
✓ db http://localhost:5432 pid 41022 ~/.config/sonar/logs/my-app/db.log
✓ api http://localhost:21408 pid 41040 ~/.config/sonar/logs/my-app/api.log
✓ frontend http://localhost:21409 pid 41077 ~/.config/sonar/logs/my-app/frontend.log
3 started
following the logs; Ctrl+C stops the 3 services started here
api | INFO: Uvicorn running on http://127.0.0.1:21408
frontend | VITE v5.4 ready in 312 ms
```
Sonar выбирает свободный порт для каждого сервиса с `port: auto` и сообщает каждому сервису, где находятся остальные, поэтому второе рабочее дерево запускается рядом с первым без единого конфликта портов. `sonar start -d` делает то же самое в фоновом режиме, а `sonar down` останавливает его и освобождает порты. В другом терминале:
```sh
sonar list --tree
```
```
my-app (3 ports, running) ~/code/my-app
├─ 5432 db postgres:17 http://localhost:5432
├─ 21408 api uvicorn app:app http://localhost:21408
└─ 21409 frontend vite (v5.4) http://localhost:21409
```
Нет `sonar.yaml`? `sonar start -- npm run dev` запускает одну команду как именованный
сервис, а `sonar list` и `sonar kill` работают со всем, что слушает.
Примеры ниже, помеченные `# check`, выполняются на свежей сборке
скриптом `scripts/readme-check.sh` при каждом запуске CI.
## Команды
### `sonar list`
```sh
sonar list
sonar list --tree
sonar list --group my-app
sonar list --json
# check
```
```sh
sonar list --stats # CPU, memory, threads, uptime, state
sonar list --health # HTTP health checks
sonar list --filter docker # only Docker ports
sonar list --sort name # port | pid | name | type
sonar list -a # include desktop apps
sonar list -c port,process,group,cpu,mem
sonar list --host user@server # scan a remote machine over SSH
```
Столбцы по умолчанию: `port`, `process`, `group`, `container`, `image`,
`containerport`, `url`, где `process` показывает имя, которое вы дали порту
(`sonar rename`), затем имя сервиса, затем то, что было обнаружено.
Доступные столбцы: `port`, `process`, `pid`, `type`, `url`, `group`, `cpu`,
`mem`, `threads`, `uptime`, `state`, `connections`, `health`, `latency`,
`container`, `image`, `containerport`, `compose`, `project`, `user`, `bind`,
`ip`.
Десктопные приложения и системные службы, которые случайно прослушивают порты — Figma, Discord,
Spotify, ControlCenter, macOS `.app` bundles, демоны `/System/Library/` —
скрыты, если не передать `-a`.
### `sonar start`
Запустить проект из его `sonar.yaml`:
```sh
sonar start # every service in the nearest sonar.yaml
sonar start api frontend # only these (they still wait for their dependencies)
sonar start ../other-project # the sonar.yaml in or above another directory
sonar start -d # in the background, like `sonar up`
```
На переднем плане sonar запускает сервисы через демон, следит за их
логами, добавляя имя сервиса перед каждой строкой, и при нажатии Ctrl+C
останавливает запущенные им сервисы. Сервис, который уже был запущен, не
затрагивается, и sonar завершается сам, как только все запущенные им сервисы
завершатся.
Аргументы перед `--` задают каталог или сервисы; всё после `--` — это
команда. Либо запустите одну команду как именованный сервис в группе:
```sh
sonar start -- npm run dev
sonar start --group my-app --name frontend -- npm run dev
sonar start --port 5173 -- npm run dev # expected port, before it binds
sonar start --detach --name api -- uv run uvicorn app:app
sonar start --list
```
Ничего передавать не нужно:
- **Group** — `--group`, иначе `name` из ближайшего `sonar.yaml`, иначе
имя каталога git-корня (worktree становится `repo@worktree`), иначе имя
текущего каталога.
- **Name** — `--name`, иначе сервис из `sonar.yaml`, чей `cmd` совпадает, иначе
выводится из команды (`npm run dev` → `dev`, `uv run api` → `api`,
`python -m uvicorn` → `uvicorn`, `./dev.sh` → `dev.sh`).
- **Port** — `--port` — это подсказка, а не привязка: запуск отображается как `starting`,
пока порт фактически не начнёт прослушиваться, и демон использует его для сопоставления
процесса с портом.
Дочерний процесс наследует stdin, stdout, stderr, cwd и окружение, а также
`SONAR_GROUP`, `SONAR_NAME` и `SONAR_RUN_ID`. Он получает собственную группу процессов,
поэтому `sonar kill` уничтожает всё дерево — dev-сервер с его наблюдателями и
воркерами. Ctrl+C перенаправляется, и sonar завершается с кодом выхода дочернего процесса.
`--detach` возвращает управление немедленно и записывает вывод в
`~/.config/sonar/logs/<group>/<name>.log`. `--list` показывает, что запустил sonar,
а под ним — что с тех пор завершилось — с кодом выхода и указанием, упало ли оно
или было остановлено (`--json` для машиночитаемого формата):
```sh
sonar start --list
sonar start --detach --name demo --port 8123 -- sleep 5
sonar start --list --json
# check
```
### `sonar.yaml`
Проект называет себя и свои сервисы в `sonar.yaml` в корне репозитория.
Он необязателен — sonar группирует по корню git и без него — и предназначен
для коммита:
```yaml
name: my-app
services:
- name: db
cmd: docker compose up db
port: 5432
health: /
description: Postgres 17
icon: database
color: "#4f8cc9"
- name: api
cmd: uv run uvicorn app:app --port 8000
cwd: backend
port: 8000
health: /healthz
depends_on: [db]
- name: frontend
cmd: npm run dev
port: 5173
depends_on: [api]
ports: [9229] # ports that belong to this project without a service
```
- `name` — имя группы. Без слэшей, без пробелов.
- `cmd`, `cwd`, `port` — как `sonar start` запускает сервис. `cwd` указывается относительно
файла и не может выходить за пределы его каталога.
- `health` — HTTP-путь, который демон опрашивает, пока сервис работает, так что
сервис может быть *запущен*, но ещё не *готов*. Он сообщает `ok`, `fail` или
`unknown`, с указанием причины сбоя.
- `description`, `icon`, `color` — свободные метаданные для десктопного приложения; sonar
никогда их не выводит сам.
- `depends_on` — порядок запуска. Указание сервиса, которого нет в файле, или
цикла — это ошибка; недействительный файл сообщается один раз и никогда не останавливает сканирование.
- `env` — переменные, устанавливаемые для сервиса, когда sonar его запускает.
#### `port: auto` и ссылки
Сервис может оставить свой порт на усмотрение sonar и находить остальные через своё
окружение вместо жёстко заданного `localhost:8080`:
```yaml
services:
- name: api
cmd: uv run uvicorn app:app --port ${port}
port: auto
- name: frontend
cmd: npm run dev -- --port ${port} --strictPort
port: auto
depends_on: [api]
env:
VITE_API_URL: ${api.url}
```
`sonar start` резервирует свободный порт для каждого сервиса `port: auto`, который он запускает: один и тот же при каждом запуске в одном и том же рабочем каталоге и разный в каждом другом, поэтому рабочее дерево никогда не конфликтует с основным. Сервис получает его как `PORT`, `SONAR_PORT` и `${port}`, и он должен его использовать — прочитать `PORT` или передать `${port}` в своей командной строке. Уже запущенный сервис сохраняет свой порт, поэтому запущенный позже всё равно его находит. Резервирование за назначенным портом сохраняется в течение дня с момента последнего запуска; `claims.ttl` изменяет это (см. The daemon).
`${port}` и `${url}` (`http://localhost:<port>`) принадлежат самому сервису; `${<service>.port}` и `${<service>.url}` — другому. Они работают в `cmd` и в `env`. Ссылка на сервис, которого нет в файле, или на сервис без порта — это ошибка при загрузке файла. Всё остальное между `${` и `}`, например `${HOME}`, остаётся точно как написано.
`sonar.yml` читается, если вы пишете именно так; `sonar init` всегда записывает `sonar.yaml`. Раньше файл был дотфайлом `.sonar.yaml`, и это имя всё ещё работает: sonar ищет `sonar.yaml`, `sonar.yml`, `.sonar.yaml` и `.sonar.yml` в этом порядке и читает первый найденный. Правки записываются обратно в файл, который прочитал sonar, так что ничего не переименовывается за вашей спиной. `sonar doctor` указывает на файл под старым именем, а `sonar doctor --fix` переименовывает его (с помощью `git mv`, когда файл отслеживается). Демон следит за известными ему проектами и подхватывает правки файла без перезапуска. Каждая правка, которую вносит sonar — из десктопного приложения, из `sonar groups add`, `rename` и `remove`, от агента — проходит через демон, который заново отрисовывает файл из собственного синтаксического дерева, поэтому комментарии, порядок ключей и разметка сохраняются при правке, добавляющей, переименовывающей или удаляющей сервис, так же как они сохраняются при изменении метаданных. Единственное исключение: лишние пробелы, выравнивающие завершающий комментарий (`cmd: x # note`), схлопываются в один, потому что библиотека YAML сохраняет комментарий, но не его колонку.
#### `sonar env`
То, во что разрешается файл, можно прочитать, ничего не запуская:
```sh
sonar env # every service: port, url and its expanded env
sonar env frontend # one service, as export lines
sonar env --json # for tools
```
```
SERVICE PORT URL ENV
db 5432 http://localhost:5432
api 21408 http://localhost:21408 DB_URL=postgres://localhost:5432/app
frontend 21409 http://localhost:21409 VITE_API_URL=http://localhost:21408
```
Сервис `port: auto`, который не запущен, получает здесь своё заявление на порт — то же самое, что делает `sonar start`, поэтому то, что выводит `sonar env`, — это то, что привяжет последующий запуск; сервис, который уже запущен, сохраняет свой текущий порт. При именованном выводе сервис представляется в виде строк `export`, чтобы оболочка могла видеть, что сервис сделал бы:
```sh
eval "$(sonar env frontend)" && npm test
```
За ним стоит `groups.env` на демоне, для редактора или агента, который подключает
рабочее дерево до того, как появятся его сервисы.
### `sonar up`
```sh
sonar up # the sonar.yaml at or above this directory
sonar up my-app # a group by name
sonar up --only api,frontend
sonar up --json
```
`sonar up` — это `sonar start -d`, который также может назвать группу из любого места и
запустить её на другом хосте. Он запускает каждый сервис, объявленный в `sonar.yaml` группы,
в порядке `depends_on`:
сервис ждёт порты, объявленные его зависимостями, прежде чем запуститься, а
тот, что уже слушает, пропускается. Каждый работает отсоединённо в своей собственной группе
процессов, с выводом в `~/.config/sonar/logs/<group>/<service>.log`, и с
окружением оболочки, в которой вы запустили `sonar up`, плюс `PORT` для сервиса
с портом.
```
✓ db http://localhost:5432 pid 41022 ~/.config/sonar/logs/my-app/db.log
- api already running
✓ frontend http://localhost:5173 pid 41108 ~/.config/sonar/logs/my-app/frontend.log
2 started, 1 already running
```
Служба, которая не запускается, сообщается отдельной строкой и приводит к тому, что команда завершается с ненулевым кодом, независимо от всего остального. Остановите их все снова с помощью `sonar down`.
`sonar up` требует демона и запускает его, если он ещё не запущен.
### `sonar down`
```sh
sonar down # the project in the nearest sonar.yaml
sonar down my-app # a group by name
sonar down --only api,worker # only these services
```
Останавливает все сервисы проекта — каждый порт, который он слушает, и каждый
сервис, запущенный sonar для него, который не занимает порт, например worker — и освобождает
порты, которые sonar зарезервировал для своих сервисов `port: auto`. `--only` сужает всё
это до указанных сервисов, так же как `sonar up --only` запускает только некоторые; имя,
не объявленное в файле, является ошибкой. `sonar kill -g my-app` останавливает порты
и ничего не освобождает.
### `sonar groups` и `sonar init`
```sh
sonar init --dry-run
sonar init --service api:8000:/healthz --service web:5173
sonar groups
sonar groups --json
group=$(basename "$PWD") # sonar init names the group after the directory
sonar groups add "$group" worker --port 9000 --cmd 'uv run worker' --depends-on api
sonar groups rename "$group" worker jobs
sonar groups remove "$group" jobs
# check
```
`sonar groups` перечисляет все группы, которые видит sonar, и откуда взялось каждое имя:
`manual` (вы закрепили его через `sonar assign`), `start` (запуск `sonar start`),
`file` (из `sonar.yaml`) или `auto` (корень git или проект Compose).
`sonar groups <name>` показывает порты и сервисы одной группы, а также сервисы,
которые объявлены, но не запущены.
`sonar init` записывает `sonar.yaml` в корне git на основе того, что можно утверждать: порты,
прослушиваемые внутри проекта прямо сейчас (настольные приложения и порты ниже 1024
исключены), плюс то, что явно объявлено в compose-файле или `package.json` — один
сервис на каждый сервис compose, с его опубликованным портом и его `depends_on`, и
скрипт `dev`, запускаемый тем менеджером пакетов, который зафиксирован в вашем lockfile.
Там, где эти два источника расходятся, побеждает прослушиваемый порт: это доказательство, а не
утверждение. В записанном файле указано то, что не удалось выяснить.
Больше ничего не обнаруживается. Цель в Makefile, строка в Procfile, точка входа,
закопанная во фреймворке, — это догадки о вашем репозитории, и таблица из них
никогда не будет закончена. Эта часть передаётся агенту:
```sh
sonar init --agent # whichever agent is installed
sonar init --agent codex # name one
sonar init --agent claude -- --allow-dangerously-skip-permissions
```
`--agent` открывает уже установленный у вас агент для программирования, в этом терминале, с уже отправленным запросом: то, что знает sonar, черновик, который он написал бы, формат и правило, что он записывает файл и ничего не запускает. Вы наблюдаете, как он читает репозиторий и одобряете его правки точно так же, как всегда — это ваш агент, под вашими разрешениями — и всё после `--` передаётся ему. sonar знает `claude`, `codex`, `cursor-agent` и `opencode`; если установлено несколько, назовите один. Когда агент завершает работу, sonar загружает файл и выводит сервисы, которые он объявляет, или причину, по которой он не загружается. Без терминала — конвейер, CI — `--agent` выводит запрос вместо того, чтобы что-либо запускать.
Он отказывается перезаписывать без `--force`, а `--dry-run` выводит файл вместо его записи. `--merge` дописывает в уже существующий файл вместо отказа, а `--service name:port[:health]` — повторяемый — записывает указанные вами сервисы вместо найденных им, сохраняя команду, которую он угадал для порта, который вы оставили. `--force` и `--merge` взаимоисключающие.
`sonar groups add <group> <name> --port N` добавляет сервис в `sonar.yaml` этой группы, с `--cmd`, `--cwd`, `--health`, `--description`, `--icon`, `--color` и повторяемым `--depends-on` для всего остального. `sonar groups rename <group> <old> <new>` переименовывает один везде в файле, включая ссылки в `depends_on`, а `sonar groups remove <group> <name>` удаляет один и убирает его из каждого `depends_on`, который его называл. Все три отказываются от правки, которая оставила бы файл недействительным — дублирующееся имя, порт, уже занятый другим сервисом, сервис, которого нет — и ни одна из них не записывает ни байта, пока вся правка не будет признана корректной.
Запись выполняет демон, поэтому файл возвращается с сохранёнными комментариями и порядком ключей независимо от того, пришла ли правка из CLI, десктопного приложения или агента. `sonar groups add`, `rename` и `remove` требуют демона и запускают его, если он ещё не запущен; эти три имени являются подкомандами, поэтому группа, фактически называющаяся `add`, читается с помощью `sonar groups --json`.
### `sonar kill`
```sh
sonar kill 3000 # SIGTERM, then SIGKILL after 5s
sonar kill 3000 5432 -f # SIGKILL both straight away
sonar kill 3000 --tree # the listener and everything below it
sonar kill --pid 12345 --tree # by process id
sonar kill -g my-app # a whole group, confirms unless -y
sonar kill --all --filter docker -y # every container publishing a port
sonar kill --all --project my-app # one Compose project
sonar kill 3000 --ip 127.0.0.1 # one bind address of several
sonar kill --all --dry-run --json # the plan for the whole machine
```
`--dry-run` принимает любой селектор и ничего не меняет: он выводит действия,
которые выполнил бы kill, сначала дочерние процессы, и оставляет всё работающим.
От начала до конца, против вашего собственного слушателя:
```sh
sonar start --detach --name plan --port 8231 -- sonar map 3000 8231
sonar wait 8231
sonar kill 8231 --dry-run --json # the plan; the mapping keeps running
sonar kill 8231 -y # and now for real
# check
```
Позиционный аргумент читается как порт и как pid только тогда, когда на этом
номере ничего не прослушивается. `-g` сопоставляет разрешённую группу, устаревший тег или
id запуска и проект Compose без учёта регистра.
Процесс, игнорирующий SIGTERM, получает SIGKILL, если порт всё ещё прослушивается
после `--grace` (5s); `--no-escalate` отключает это. Дочерние процессы получают сигнал
раньше родительских, поэтому дерево завершается по порядку. Контейнеры Docker
останавливаются с помощью `docker stop` и никогда не получают сигналов. Слушатель, запущенный
`sonar start`, всегда останавливается вместе со своей группой процессов.
`--json` выводит одну строку на процесс:
`{port, bind_address, pid, name, method, ok, error}`, где `method` — это
`sigterm`, `sigkill`, `docker_stop`, `map_stop` или `none`. Пустой sweep завершается
с кодом 0; неизвестная группа завершается с кодом 1.
### `sonar map`
```sh
sonar map 6873 3002 # also serve the service on 6873 from port 3002
```
Запускает TCP-прокси на переднем плане, пока вы его не остановите. `sonar kill` сообщает
остановленное сопоставление как `map_stop`.
### `sonar rename`, `sonar assign`, `sonar history`
```sh
sonar rename 3000 storefront # a name of your own, survives restarts
sonar rename 3000 --clear
sonar assign 3000 my-app # pin a port to a group by hand
sonar assign 3000 --clear
sonar history # everything that came up, went down, restarted
sonar history 3000 --since 24h --limit 20
```
```sh
sonar history --since 1h
sonar history --json
# check
```
Имена и привязки хранятся в базе данных sonar с ключом по наиболее конкретной известной информации о порту: запуск (`run:<group>/<name>`), контейнер (`docker:<project>/<service>`), рабочий каталог и, наконец, номер порта. Переименованный dev-сервер сохраняет своё имя между перезапусками; имя, привязанное только к порту 3000, применяется к тому, что отвечает на этом порту. Эти три команды требуют демона и запускают его, если он не запущен.
### Чтение порта
```sh
sonar info 3000 # command, user, bind, stats, health
sonar logs 3000 # tail; docker logs for containers
sonar wait 5432 3000 --timeout 60s # block until ready
sonar wait 5432 --http=/health # wait for HTTP 200-399, not just TCP
sonar next 3000 # first free port from 3000
sonar next 3000-3100 -n 3 # three consecutive free ports
sonar graph # who is connected to whom
sonar graph --dot # Graphviz
sonar open 3000 # open in the browser
sonar attach 3000 # shell into the container, or TCP
sonar watch # live view
sonar watch --stats --notify
```
```sh
sonar next 3000
sonar next 3000-3100 -n 3 --json
sonar graph --json
sonar info --help
# check
```
`sonar wait` завершается с кодом `0` (готово), `1` (тайм-аут) или `2` (прервано), что делает
---
[Read more](https://github.com/raskrebs/sonar)