## 설치

### Homebrew (macOS / Linux)```sh
brew install raskrebs/sonar/sonar

### 설치 스크립트```sh
curl -sfL https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.sh | bash

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

I need the actual content of chunk 17 to translate it. Please provide the Markdown text you'd like translated from English to Korean.```powershell
$env:SONAR_VERSION="vX.Y.Z"; irm https://raw.githubusercontent.com/raskrebs/sonar/main/scripts/install.ps1 | iex

Shell 완성 (탭 완성 포트 번호):```sh
sonar completion zsh > "${fpath[1]}/_sonar"   # zsh
sonar completion bash > /etc/bash_completion.d/sonar  # bash
sonar completion fish | source                 # fish

그룹 이름은 저장소에서 가져오므로 다른 설정은 필요하지 않습니다.
다른 터미널에서:```sh
sonar list --tree

그리고 작업이 끝나면 전체 프로젝트(서버, watcher, worker)를 중지하세요:```sh
sonar kill -g my-app

I need the actual content of chunk 33 to translate it. Please provide the Markdown text you want translated.```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

아무것도 전달할 필요가 없습니다:

- **Group** — `--group`, 그 외에는 가장 가까운 `.sonar.yaml`의 `name`, 그 외에는
  git 루트 디렉터리 이름(worktree는 `repo@worktree`가 됨), 그 외에는
  현재 디렉터리의 이름.
- **Name** — `--name`, 그 외에는 `cmd`가 일치하는 `.sonar.yaml` 서비스, 그 외에는
  명령에서 유추됨(`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`은 전체 트리를 종료합니다 — watcher와 worker를 포함한
개발 서버 전체를 말입니다. 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

- `name` — 그룹 이름. 슬래시나 공백 없음.
- `cmd`, `cwd`, `port` — `sonar up`이 서비스를 시작하는 방식. `cwd`는 파일 기준 상대 경로이며 해당 디렉터리를 벗어날 수 없음.
- `health` — 데몬이 서비스가 실행되는 동안 폴링하는 HTTP 경로로, 서비스가 *실행 중*이지만 아직 *정상*이 아닐 수 있음. `ok`, `fail` 또는 `unknown`을 보고하며, 실패 시 이유도 함께 보고함.
- `description`, `icon`, `color` — 데스크톱 앱용 자유 형식 메타데이터. sonar는 이를 추론하지 않음.
- `depends_on` — 시작 순서. 파일에 없는 서비스를 지정하거나 순환 참조가 있으면 오류. 잘못된 파일은 한 번 보고되며 스캔을 중단하지 않음.

`.sonar.yml`은 그렇게 철자하는 경우 읽히며, `sonar init`은 항상 `.sonar.yaml`을 작성함. 데몬은 알고 있는 프로젝트를 감시하며 파일 편집을 재시작 없이 반영함. sonar가 수행하는 모든 편집(데스크톱 앱, `sonar groups add`, `rename`, `remove`, 에이전트에서)은 데몬을 거치며, 데몬은 자체 구문 트리에서 파일을 다시 렌더링하므로 주석, 키 순서 및 레이아웃은 서비스를 추가, 이름 변경 또는 제거하는 편집에서도 메타데이터 변경과 마찬가지로 유지됨. 한 가지 예외: 후행 주석을 정렬하는 추가 공백(`cmd: x     # note`)은 하나로 축소되는데, 이는 YAML 라이브러리가 주석은 유지하되 열 위치는 유지하지 않기 때문임.

### `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

서비스가 시작에 실패하면 해당 서비스는 자체 줄에 보고되며, 다른 어떤 결과와 관계없이 명령이 0이 아닌 종료 코드를 반환하게 합니다. `sonar kill -g my-app`으로 모두 다시 중지하세요. `sonar up`은 데몬이 필요하며, 이미 실행 중이 아니라면 데몬을 시작합니다.

### `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

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

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

sonar의 데이터베이스에는 포트에 대해 알려진 가장 구체적인 정보를 키로 하여 이름과 핀이 저장됩니다: 실행(`run:<group>/<name>`), 컨테이너(`docker:<project>/<service>`), 작업 디렉터리, 그리고 마지막으로 포트 번호입니다. 이름이 변경된 개발 서버는 재시작 후에도 이름을 유지하며, 포트 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

`sonar wait`는 `0`(준비됨), `1`(시간 초과) 또는 `2`(중단됨)로 종료되므로,
무언가를 시작한 후 테스트하기 전에 넣기에 적합한 명령입니다:```sh
docker compose up -d
sonar wait 5432 3000 --timeout 60s && npm run migrate && npm run test

### `sonar host````sh
sonar host          # cpu, load, memory and disk of the machine sonar watches
sonar host --json

데몬은 스캔 주기에 맞춰 자신의 머신을 측정하고, 이를 스냅샷의 `hosts` 컬렉션에 `localhost` 행으로 게시합니다: OS와 커널, 가동 시간, CPU 퍼센트, 부하 평균, 메모리, 그리고 `/`를 보유한 디스크입니다. CPU 퍼센트는 두 스캔 사이에 수행된 작업이므로, 데몬이 두 번 스캔하기 전까지는 null입니다. 플랫폼이 생성할 수 없는 수치(예: 부하 평균이 없는 Windows의 부하 평균)는 0이 아닌 null입니다. `sonar remote add`로 등록된 모든 호스트는 자체 부하와 함께 동일한 테이블에 합류합니다. 이 명령은 실행 중인 데몬이 필요합니다. 퍼센트가 측정되는 이전 샘플을 보유하는 것은 데몬이기 때문입니다.

### `sonar remote install````sh
sonar remote install [email protected]        # same version as this sonar
sonar remote install hetzner --version v0.6.0  # a Host from ~/.ssh/config
sonar remote install deploy@box --no-service   # the binary, no daemon

등록된 호스트는 동일한 데몬을 실행하며, 이 머신의 데몬은 해당 호스트에 SSH 연결 하나를 유지합니다 — `ssh <target> sonar daemon stdio` — 그리고 보고하는 내용을 모든 클라이언트가 이미 읽는 상태로 다중화합니다. 어디에도 새로 수신 대기하는 것이 없습니다. 원격 데몬의 소켓은 SSH 사용자에게만 비공개로 유지되며, 클라이언트는 스스로 SSH를 사용하지 않습니다.

이제 모든 행에는 해당 행이 출처한 호스트가 포함됩니다. 로컬 행은 `localhost`라고 표시되고 기존에 항상 가졌던 키를 유지하므로, 오늘 sonar를 읽는 어떤 것도 변경되지 않습니다. 원격 행은 등록된 이름을 표시하고 `<host>/<port>:<bind>`로 키가 지정되며, 이 덕분에 두 머신의 포트 3000이 두 개의 행이 될 수 있습니다. 구독자는 더 많은 것을 요청하지 않는 한(`state.subscribe {"hosts": ["*"]}`) localhost만 볼 수 있습니다.

대상은 수정 없이 `ssh`로 전달되므로 `~/.ssh/config` 별칭, `ProxyJump` 및 자격 증명이 모두 적용됩니다. `--ssh-arg`, `--identity` 및 `--port`는 config가 다루지 않는 부분을 처리합니다. sonar는 비밀번호나 키를 저장하지 않습니다. 사라진 호스트는 데몬이 재시도하는 동안 해당 행과 상태를 유지하며, 등록된 상태로 유지되는 한 1초에서 30초로 백오프합니다.

`--host`는 또한 sonar가 전혀 알지 못하는 단순한 `user@host`도 계속 받아들입니다. 이 경우 에이전트 없는 `ssh` + `ss`/`lsof` 스캔으로 대체되고 `sonar remote install`에 대한 힌트를 출력합니다.

#### 다른 머신에서 작업 수행

모든 쓰기 작업도 `--host`를 받으며, 여기서 수행하는 것과 정확히 동일하게 해당 머신에서 수행합니다.```sh
sonar kill 3000 --host hetzner                 # stop a port on that machine
sonar kill -g api --host hetzner               # a whole group of its services
sonar kill-all --filter docker --host hetzner  # its containers
sonar up api --host hetzner                    # start a group from its .sonar.yaml
sonar logs 3000 --host hetzner                 # tail its output here
sonar rename 3000 storefront --host hetzner    # its name, in its database
sonar assign 3000 storefront --host hetzner

# 4.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.2.```sh
sonar daemon path
sonar daemon status --json
sonar daemon log -n 5
# check

이 도구는 사용자가 지정한 시간 간격으로 지정된 명령을 실행할 수 있게 해주며, 지속적인 모니터링이나 자동화된 작업에 유용합니다. 또한 명령 실행 결과를 로그 파일에 기록하여 나중에 검토할 수 있도록 지원합니다. 이 기능은 보안 분석가가 시스템 상태를 추적하거나 특정 이벤트를 주기적으로 확인해야 할 때 특히 유용합니다.```sh
sonar config edit       # open it in $EDITOR

잘못된 값은 경고와 함께 무시되며 sonar는 기본값으로 계속 진행합니다.
구성 키가 없는 환경 변수 재정의: `SONAR_DB`, `SONAR_SOCKET`,
아래의 마이그레이션 알림을 끄려면 `SONAR_NO_HINTS=1`, 그리고
찾지 못한 데몬을 sonar 클라이언트가 시작하지 못하게 하려면 `SONAR_NO_AUTOSTART=1` — 빌드가 프로세스를 남겨서는 안 되는 CI에서 유용합니다.

sonar 자체 테스트 스위트는 모든 테스트 바이너리에 대해 `SONAR_NO_AUTOSTART=1`을 설정하고,
실행 후에는 이를 초과해 살아남은 데몬을 찾습니다. 해당 게이트는 실행의
개인 임시 루트에서 시작된 `serve`만 대상으로 하므로, 한 머신에서 나란히 실행되는
두 스위트는 서로의 데몬을 건드리지 않습니다;
`SONAR_TESTENV_GATE_ALL=1`은 이를 임시 디렉터리 아래 어디에 있든 모든 `sonar serve`로
다시 확장하며, 이는 전체 머신을 소유한 CI 러너가 원하는 방식입니다.

### 에이전트: MCP, 스킬 및 훅```sh
sonar install mcp --claude-code               # merge into <git root>/.mcp.json
sonar install mcp --cursor --scope user       # ~/.cursor/mcp.json
sonar install mcp --codex                     # codex mcp add
sonar install skills --claude-code            # the bundled sonar skill
sonar install hooks --claude-code             # optional, see below

`install mcp`는 `{"command": "sonar", "args": ["mcp"]}`를 등록하고 파일의 다른 모든 서버와 키는 그대로 둡니다. 두 번 실행해도 아무 변화가 없으며, `--uninstall`은 sonar가 기록한 것만 정확히 제거합니다.

`sonar mcp`는 바로 그 서버입니다. 바이너리에 내장된 stdio MCP 서버로, 에이전트에게 데몬이 보는 머신의 관점을 제공합니다. `list_ports`와 `inspect_port`로 읽고, `wait_for_port`로 대기하며, `next_free_port`와 `claim_port`로 포트를 선택하고 예약합니다. 그리고 에이전트의 나머지 질문에는 `tail_logs`, `health_check`, `dependency_graph`, `port_history`, `list_sessions`로 답합니다. 액션과 리소스는 그 다음에 옵니다. 실행 중인 데몬이 없으면 시작하고, 데몬이 사라지면 스스로 재연결합니다. 로그는 stderr로 출력되는데, stdout이 프로토콜을 전달하기 때문입니다.

`install skills`는 번들된 스킬을 기록합니다. 이 스킬은 에이전트에게 `sonar start --`로 서버를 시작하고, 잠자기 대신 `sonar wait`를 사용하며, 시작한 것을 정리하도록 가르칩니다. `install hooks`는 두 개의 Claude Code 훅을 추가합니다. 하나는 `SONAR_SESSION`을 내보내 세션에서 시작한 모든 것이 해당 세션에 귀속되게 하고, 다른 하나는 베어 개발 서버가 실행되려 할 때 `sonar start --`를 제안합니다(조언만 하며 차단하지 않습니다). 둘 다 `--scope project|user`, `--print`, `--uninstall`을 지원합니다.

### `sonar doctor`

sonar가 의존하는 모든 것을 점검하고 문제가 있을 때 무엇을 해야 하는지 알려주는 단일 명령입니다. 데스크톱 앱이 온보딩 중 실행하는 것이며, 무언가 이상할 때 직접 실행해야 하는 명령이기도 합니다.```sh
sonar doctor                       # the table, and a one-line verdict
sonar doctor --json                # {ok, checks, version, daemon_version}
sonar doctor --only db_ok,tray     # just these
sonar doctor --only mcp_registered # a whole family
sonar doctor --project ~/code/api  # a project other than the working directory
sonar doctor --fix --yes           # apply the safe repairs, then check again

모든 검사는 `ok`, `warn`, `fail` 또는 `skip`을 보고합니다. `skip`은 검사할 대상이 없다는 뜻입니다 — Cursor가 설치되지 않았거나, 머신에 docker가 없거나, 소켓이 Windows의 named pipe인 경우 등이며, 절대 불이익으로 작용하지 않습니다. 무언가 **실패**하지 않는 한 종료 코드는 0이므로, `sonar doctor`는 설정 스크립트에 포함하기 적합합니다.

| check | 의미 |
| --- | --- |
| `cli_on_path` | 실행한 바이너리가 PATH가 해석하는 것인지 확인하며, 그렇지 않으면 가리는 설치를 이름으로 알려줍니다 |
| `cli_version_current` | 최신 릴리스와 비교하며, GitHub에 2초 내에 연결할 수 없으면 `skip` |
| `config_parses` | `config.yaml`이 로드되는지 확인하며, 구문 오류는 줄, 열, 캐럿(^)과 함께 보고됩니다 |
| `config_dir_writable` | 데몬이 로그, 잠금 파일, 데이터베이스를 쓸 수 있는지 확인 |
| `daemon_reachable` | 소켓에서 무언가가 수신 대기 중인지 확인 |
| `daemon_version_matches` | 실행 중인 데몬이 사용 중인 CLI 버전과 일치하는지 확인 |
| `daemon_protocol` | 데몬의 프로토콜 메이저 버전이 이 빌드와 일치하는지 확인 |
| `socket_permissions` | 소켓이 사용자 소유이고 0600 권한이며, 0700 디렉터리에 있는지 확인 (Windows에서는 `skip`) |
| `db_ok` | 데이터베이스가 열리고 최신 스키마인지, 크기가 얼마인지 확인 |
| `mcp_registered.{claude_code,cursor,codex}` | sonar의 MCP 서버가 해당 클라이언트의 설정에 있는지 확인 |
| `skills_installed` | 번들된 스킬이 설치되어 최신 상태인지 확인 |
| `hooks_installed` | 선택적 Claude Code 훅이 설치되어 있는지 확인 |
| `project_config` | 이 프로젝트에 로드 가능한 `.sonar.yaml`이 있는지 확인 |
| `docker` | docker CLI가 있고 데몬이 응답하는지 확인 |
| `desktop_installed` | 데스크톱 앱이 설치되어 있는지, 어떤 버전인지 확인 (Windows에서는 `skip`) |
| `tray` | 대체된 macOS `sonar-tray` 바이너리가 아직 남아 있는지 확인 |

`--fix`는 무인으로 실행해도 안전한 수리만 적용하며, `--yes`를 전달하지 않으면 먼저 확인을 요청합니다: 구문 분석이 불가능한 `config.yaml`을 `config.yaml.broken-<timestamp>`로 이동시키고 새 템플릿을 작성하며(아무것도 삭제되지 않음), 실행 중이지 않은 데몬을 재시작하고, 검사가 지목하는 `sonar install mcp|skills|hooks` 명령을 실행합니다 — 작업 디렉터리에서 직접 입력하는 방식으로 실행되므로, `--project`로 가리키기보다는 수리 중인 프로젝트 내부에서 `--fix`를 실행하세요. 그런 다음 다시 검사합니다. 건드리지 않는 항목 — PATH의 가리는 바이너리, sonar가 작성하지 않은 스킬 — 은 `fix` 열의 정확한 명령과 함께 사용자에게 맡겨집니다.

데스크톱 앱은 셸을 호출하는 대신 데몬의 `daemon.doctor` 메서드를 통해 동일한 검사를 호출합니다. 데몬은 자체 프로세스에서 가능한 모든 것을 실행하며, 호출한 CLI 바이너리에 관한 세 가지 검사(`cli_on_path`, `cli_version_current`, `daemon_version_matches`)는 해당 사항을 설명하는 세부 정보와 함께 `skip`으로 반환됩니다.

### 데스크톱 앱

Sonar 앱은 창과 메뉴 바 또는 시스템 트레이에 동일한 화면을 표시합니다: 측면에 그룹, 실시간 통계와 상태가 있는 그리드의 포트, 로그, 그리고 위의 모든 항목에 대한 버튼이 있습니다. 동일한 데몬과 통신하므로 CLI와 앱이 서로 불일치하지 않습니다. `sonar install desktop`이 설치하고 `sonar tray`가 실행합니다.

앱이 출시될 때까지 macOS 릴리스 tarball에는 여전히 이전 `sonar-tray` 메뉴 바 바이너리가 포함되어 있으며, 앱이 설치되지 않은 경우 `sonar tray`가 해당 바이너리로 대체됩니다.

### `sonar install desktop`

앱은 베타 버전이며 아직 Apple 서명이 되지 않았으므로, CLI가 설치를 수행합니다:```sh
brew install raskrebs/sonar/sonar && sonar install desktop

명령어는 네트워크 없이도 무엇을 하는지 알려줍니다:```sh
sonar install desktop --help | grep -- '--no-launch'
# check

`docs/RELAY.md`에는 라우트, 정확한 검증 규칙, 스토리지 스키마, 그리고 Docker가 있는 모든 박스에서 Caddy 뒤에 한 번의 명령으로 배포하는 방법이 포함되어 있습니다.

## 이전 명령에서 전환하기

그룹 이전 명령은 여전히 동작하며, 이를 대체한 항목을 알려주는 한 줄을 stderr에 출력합니다. 이 명령들은 지금부터 한 번의 마이너 릴리스 후에 제거됩니다. `SONAR_NO_HINTS=1`은 알림을 숨기며, `--json` 출력에는 절대 포함되지 않습니다.

| 이전 | 새 명령 |
|---|---|
| `sonar run --tag X -- cmd` | `sonar start --group X -- cmd` |
| `sonar runs` | `sonar start --list` |
| `sonar list --tag X` | `sonar list --group X` |
| `sonar kill-all --filter docker` | `sonar kill --all --filter docker` |
| `sonar down X` | `sonar kill -g X` |
| `sonar profile create X` | `sonar init` |
| `sonar profile show X` | `sonar groups X` |
| `sonar up X` (프로필 확인) | `sonar up X`는 이제 그룹을 *시작*합니다 |
| `sonar tray` (Swift 메뉴 바 앱) | `sonar tray`는 데스크톱 앱을 실행합니다 |

프로필은 머신별 포트 스냅샷이었습니다. `.sonar.yaml`은 프로젝트와 함께 커밋됩니다. 하나를 변환한 후 유지하기 전에 읽어보세요 — 자동으로 작성되는 것은 없습니다:```sh
sonar profile list
# check

프로필은 서비스가 어떻게 시작되는지 기록하지 않으므로, 제안에는 포트, 이름, 헬스 경로가 포함되며 `cmd`는 직접 채워 넣습니다.

## 문제 해결

**데몬에 문제가 있습니다.** 문제를 재현하는 동안 `sonar daemon log -f`를 실행하고, `sonar daemon status`로 PID, 가동 시간, 스캔 횟수를 확인하세요. `sonar daemon stop`으로 중지할 수 있으며, 데몬 없이도 모든 읽기 명령은 계속 작동합니다.

**"daemon unavailable, using direct scan".** 소켓에서 수신 대기 중인 프로세스가 없습니다. 이는 정상입니다 — 읽기 작업은 데몬을 시작하지 않습니다. 데몬이 필요하면 `sonar serve -d`를 실행하세요.

**크래시로 남은 소켓.** `sonar daemon path`로 확인할 수 있으며, 데몬을 시작하면 오래된 소켓은 자동으로 제거됩니다. 첫 번째 데몬이 사라졌는데도 두 번째 데몬이 시작을 거부한다면, `sonar daemon restart`로 잠금을 해제하세요.

**목록에서 포트가 누락되었습니다.** 다른 사용자가 소유한 프로세스는 권한이 없으면 보이지 않습니다. sonar는 표 아래에 이를 명시합니다. `sudo sonar list`로 다시 실행하면 볼 수 있습니다. Linux에서는 `ss`가 설치되어 있어야 하며(`iproute2`), Windows에서는 `netstat`이 사용됩니다.

**kill이 아무 효과가 없었습니다.** Docker 컨테이너는 Docker 데몬을 통해 중지됩니다: `docker ps`를 확인하세요. SIGTERM을 무시하는 프로세스는 `-f`가 필요하며, 다른 것(systemd, Compose `restart: always`)이 관리하는 프로세스는 설계상 다시 시작됩니다 — 관리자를 중지하세요.

**아무것도 작동하지 않고 이유를 모르겠습니다.** `sonar doctor`는 바이너리, 설정, 데몬, 데이터베이스 및 모든 통합을 한 번에 점검하고, 발견된 각 항목을 수정하는 명령을 출력합니다.

**버그 신고.** 다음 항목과 `sonar daemon log`의 마지막 줄을 포함하세요:```sh
sonar version
sonar daemon status
sonar doctor --json
# check