
localhost पोर्ट पर सुनने वाली सेवाओं के निरीक्षण और प्रबंधन के लिए CLI उपकरण
<div align="center">
```
██████ ███ ██████ ██ ██████
██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ██
██ ██ ██ ██ ██ ██ ██ ████
██ ██ ██ ██ ██ ██ ██ ██
██████ ███ ██ ██ ██ ██ ██ ██
```
जानें कि आपकी मशीन पर क्या चल रहा है।
</div>
Sonar localhost पर सुन रही हर चीज़ को दिखाता है और उसे क्रम में लगाता है: हर पोर्ट
एक **group** से संबंधित होता है — सामान्यतः वह repository जहाँ से उसे शुरू किया गया था — और
उस group के अंदर एक नामित **service** से। अपने dev servers को
`sonar start` से शुरू करें और पूरा project एक ऐसी चीज़ बन जाता है जिसे आप एक tree के रूप में list कर सकते हैं,
उसका इंतज़ार कर सकते हैं, tail कर सकते हैं, और एक ही command से बंद कर सकते हैं। Docker containers, Compose
projects और आपके द्वारा हाथ से शुरू किए गए processes भी बिना किसी
configuration के उठा लिए जाते हैं।
```
$ 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 एक बार टैप पर भरोसा करने तक तीसरे पक्ष के टैप्स से फ़ॉर्मूले लोड करने से मना कर देता है
(`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
```
Shell पूर्णताएँ (टैब-पूर्ण पोर्ट संख्याएँ):
```sh
sonar completion zsh > "${fpath[1]}/_sonar" # zsh
sonar completion bash > /etc/bash_completion.d/sonar # bash
sonar completion fish | source # fish
```
## साठ सेकंड
`dev.sh` के स्थान पर, रिपॉज़िटरी रूट में `sonar.yaml` में बताएं कि आपका प्रोजेक्ट कैसे चलता है:
```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` सेवा के लिए एक मुफ़्त पोर्ट चुनता है और प्रत्येक सेवा को बताता है कि अन्य कहाँ हैं, ताकि दूसरा worktree पहले के बगल में बिना किसी पोर्ट टकराव के चल सके। `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` के रूप में चिह्नित उदाहरण हर CI रन पर `scripts/readme-check.sh` द्वारा एक नए बिल्ड के विरुद्ध निष्पादित किए जाते हैं।
## कमांड
### `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` बंडल, `/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`, अन्यथा निकटतम `sonar.yaml` में `name`, अन्यथा
git root की directory का नाम (एक worktree `repo@worktree` बन जाता है), अन्यथा वर्तमान directory का नाम।
- **Name** — `--name`, अन्यथा वह `sonar.yaml` service जिसका `cmd` मेल खाता है, अन्यथा
command से अनुमानित (`npm run dev` → `dev`, `uv run api` → `api`,
`python -m uvicorn` → `uvicorn`, `./dev.sh` → `dev.sh`)।
- **Port** — `--port` एक संकेत है, binding नहीं: run तब तक `starting` दिखाता है
जब तक port वास्तव में listening न हो जाए, और daemon इसका उपयोग process को
port से मिलाने के लिए करता है।
child stdin, stdout, stderr, cwd और environment विरासत में लेता है, साथ ही
`SONAR_GROUP`, `SONAR_NAME` और `SONAR_RUN_ID` भी। इसे अपना process group मिलता है,
इसलिए `sonar kill` पूरे tree को समाप्त कर देता है — एक dev server अपने watchers और
workers सहित। Ctrl+C आगे भेजा जाता है, और sonar child के exit code के साथ बाहर निकलता है।
`--detach` तुरंत लौटता है और output को
`~/.config/sonar/logs/<group>/<name>.log` में लिखता है। `--list` दिखाता है कि sonar ने क्या शुरू किया,
और उसके नीचे वह जो तब से समाप्त हो चुका है — exit code के साथ, और क्या वह crash हुआ
या रोका गया (`--json` machine-readable रूप के लिए):
```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` वाली सेवा जो चल नहीं रही है, उसे यहाँ उसका claim दिया जाता है, वही claim जो `sonar start` बनाता है, इसलिए `sonar env` जो प्रिंट करता है वही बाद में start होने पर bind होता है; जो सेवा पहले से चल रही है वह अपने मौजूदा port पर ही रहती है। नाम देने पर, सेवा `export` लाइनों के रूप में निकलती है, ताकि shell देख सके कि सेवा क्या करेगी:
```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` सेवाओं के लिए claim किया था। `--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 root या Compose प्रोजेक्ट)।
`sonar groups <name>` एक समूह के पोर्ट और सेवाएँ दिखाता है, और वे सेवाएँ
जो घोषित हैं लेकिन चल नहीं रही हैं।
`sonar init` जो कुछ भी बता सकता है उससे git root पर एक `sonar.yaml` लिखता है: वे
पोर्ट जो इस समय प्रोजेक्ट के अंदर सुन रहे हैं (डेस्कटॉप ऐप्स और 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` परस्पर अनन्य हैं।
---
[Read more](https://github.com/raskrebs/sonar)