SonarQube CLI
Build
Quality Gate Status
프로덕션에 도달하기 전에 터미널에서 코드 품질 및 보안 문제를 포착하세요.
SonarQube CLI는 엔터프라이즈급 정적 분석(static analysis)을 개발 워크플로우에 통합합니다:
- 🔒 비밀 정보 감지 (Secret Detection) — 하드코딩된 자격 증명(hardcoded credentials)을 스캔하고 비밀 정보가 LLM 제공업체로 전송되는 것을 방지합니다.
- ⚡ 빠른 피드백 루프 (Fast Feedback Loop) — CI/CD를 기다릴 필요 없이 로컬 변경 사항에 대한 서버 측 이슈 감지를 받습니다.
- 🤖 AI 지원 수정 (AI-Assisted Fixes) — 보안 취약점(security vulnerabilities)에 대한 복구 제안을 생성합니다 (SonarQube Cloud).
- 🔗 에이전트 통합 (Agent Integration) — Claude Code, GitHub Copilot CLI, Codex, Cursor, Antigravity, OpenCode, Devin, Pi를 위한 원활한 후크(hooks).
- 📊 스크립팅 가능 (Scriptable) — JSON 출력을 사용하여 SonarQube 이슈를 프로그래밍 방식으로 조회하고 관리합니다.
단독으로 사용하거나 다음 항목과 통합할 수 있습니다: Git hooks, Claude Code, GitHub Copilot CLI, Codex, Cursor, Antigravity, OpenCode, Devin, Pi, CI/CD 파이프라인, 사용자 지정 자동화
🤖 AI 에이전트용: 만약 이 내용을 읽는 AI 에이전트라면, LLM 사용에 최적화된 기계 판독 가능(machine-readable) 명령어 문서를 얻기 위해 docs/llms.txt로 이동하십시오.
저희는 이 제품에 대한 피드백을 적극적으로 수집하고 있습니다. 이 양식을 통해 의견을 공유해 주십시오!
문서화 (Documentation)
목차 (Table of Contents)
이 CLI를 사용하는 세 가지 방법
SonarQube CLI는 세 가지의 뚜렷한 사용 사례를 위해 설계되었습니다:
-
🤖 에이전트 기반 사용 (Agentic Use) — AI 코딩 에이전트(Claude Code, GitHub Copilot CLI, Codex, Cursor, Antigravity, OpenCode, Devin, Pi)에 대한 내장 지원을 제공하며, 비밀 정보가 LLM 공급자에게 전송되는 것을 방지하는 안전 장치가 마련되어 있습니다.
sonar integrate claude
이제 Claude Code는 코드를 처리하기 전에 자동으로 비밀 정보를 스캔합니다
2. **🖥️ 대화형 CLI (Interactive CLI)** — 터미널에서 직접 명령을 실행하여 코드를 스캔하고, 이슈를 확인하며, SonarQube 프로젝트를 수동으로 관리할 수 있습니다.
```bash
sonar list issues --project my-app
sonar analyze --file file.ext
- ⚙️ 스크립팅 및 자동화 (Scripting & Automation) — 보고서, 대시보드 또는 자동 품질 게이트(automated quality gates)를 위해 스크립트에 통합할 수 있습니다.
sonar list projects | jq -r '.projects[].key' | while read project; do
echo "Project: $project"
...
## 사전 요구 사항
설치하기 전에 다음이 필요합니다:
- **SonarQube 접속 방식** (택일):
- [SonarQube Cloud](https://sonarcloud.io) — 오픈 소스 프로젝트는 무료, 비공개 저장소는 유료
- SonarQube 서버 — 자체 호스팅 인스턴스 (v25.1 이상)
- **운영 체제**: Linux (x86-64, ARM64), macOS (ARM64), 또는 Windows (x86-64)
**선택 사항:**
- Git 2.x+ (git hook 통합용)
- Claude Code, GitHub Copilot CLI, Codex, Cursor, Antigravity, OpenCode, Devin, 또는 Pi (AI 어시스턴트 통합용)
**SonarQube를 처음 사용하시나요?** [무료 SonarQube Cloud 계정 생성](https://sonarcloud.io/sessions/new) — 오픈 소스 프로젝트의 경우 신용카드 필요 없음.
## 빠른 시작 (Quick Start)
### 단계 1: 설치 (Install)
설정 환경에 맞는 설치 채널을 선택하세요:
**Homebrew (macOS/Linux):**
```bash
brew install sonarqube-cli
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
Mise (macOS, Linux 또는 Windows):
mise use -g sonarqube-cli@latest
설치 스크립트 (Linux/macOS):
curl -o- https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.sh | bash
설치 스크립트 (Windows, PowerShell에서 실행):
irm https://raw.githubusercontent.com/SonarSource/sonarqube-cli/refs/heads/master/user-scripts/install.ps1 | iex
설치 확인:
참고: 설치 스크립트를 사용한 후에는 업데이트된 PATH가 다시 로드되도록 터미널을 재시작하세요. Homebrew는 PATH를 자동으로 관리하며, Mise는 셸 활성화가 이미 구성되었다고 가정합니다.
단계 2: 인증 (Authenticate)
SonarQube Cloud EU에 연결 (기본값):
SonarQube Cloud US용:
sonar auth login --server https://sonarqube.us
자체 호스팅 SonarQube 서버용:
sonar auth login --server https://sonarqube.mycompany.com
인증 확인:
자동화(automation), CI/CD, 그리고 AI 에이전트의 경우, 토큰을 환경 변수(environment variables)를 통해 전달해야 합니다. CLI는 명령 실행 시점에 이를 읽기 때문에 디스크나 OS 키체인에 아무것도 기록되지 않습니다.
먼저 토큰을 생성합니다: SonarQube → 내 계정(My Account) → 보안(Security) → 토큰 생성(Generate Token).
그런 다음 sonar를 호출하기 전에 다음 환경 변수들을 정의합니다 (CI에서는 러너의 비밀 저장소(secret store)를 사용하거나, 선호하는 로컬 메커니즘 — direnv, 추적되지 않는 .env 파일, 암호 관리자 CLI 등 — 을 사용하세요):
- SonarQube Cloud:
SONARQUBE_CLI_TOKEN + SONARQUBE_CLI_ORG
- Self-hosted SonarQube Server:
SONARQUBE_CLI_TOKEN + SONARQUBE_CLI_SERVER
이 변수들을 내보내면(exported), 추가 구성 없이 모든 명령이 작동합니다:
두 변수 모두 설정하세요. 만약 SONARQUBE_CLI_TOKEN만 존재할 경우, CLI는 표준 에러(stderr)에 경고를 출력하고 키체인 자격 증명(keychain credentials)으로 폴백(fall back)하지만, 이는 자동화 환경에서 거의 원하는 동작이 아닙니다. 토큰을 절대 커밋하거나 CLI 인수로 전달하지 마세요.
3단계: 기본 명령어 사용해 보기 (Try Basic Commands)
프로젝트 목록 확인:
출력은 기본적으로 JSON 형식입니다. jq를 통해 임시 필터링을 할 수 있습니다. 예: sonar list projects | jq -r '.projects[].key'.
파일에서 비밀 정보(secrets) 스캔:
cat > test.js <<'EOF'
const STRIPE_KEY = "sk_live_<PASTE_A_REAL_STRIPE_KEY_HERE>";
EOF
...
비밀 정보가 발견되면, 해당 명령어는 코드 51로 종료됩니다.
프로젝트의 이슈 확인:
sonar list issues --project my-org_my-app --format table --page-size 3
...
지원되는 형식: json(기본값), table, toon, csv.
💡 팁: --project 플래그는 종종 선택 사항입니다. 작업 디렉터리에 sonar-project.properties 파일이 있거나 .sonarlint/ 아래에 SonarLint connected-mode 바인딩이 있는 경우, CLI가 해당 위치에서 프로젝트 키를 자동으로 가져옵니다.
4단계: 로컬 변경 사항 분석 (SonarQube Cloud 전용)
cd your-project-directory
sonar analyze --file file.ext
...
일반 옵션:
sonar analyze --file src/myfile.ts
sonar analyze --base main
sonar analyze --branch feature-xyz
통합 (Integrations)
Claude Code 통합
이 훅은 이 장치의 모든 Claude Code 세션에 적용됩니다:
sonar auth login
sonar integrate claude
이를 통해 다음 기능이 설치됩니다:
- 비밀 스캐닝을 위한 Pre-tool-use hook — 하드코딩된 자격 증명이 LLM 제공업체로 전송되는 것을 방지합니다.
- SonarQube Agentic Analysis 통합 — 워크플로우 내에서 서버 측 코드 품질 분석이 가능합니다.
- Model Context Protocol (MCP) 서버 — Claude Code에서 SonarQube 데이터에 직접 접근할 수 있습니다.
Git Hooks
이 훅은 이 장치의 모든 저장소에 적용됩니다:
Pre-commit hook (커밋 전 스테이징된 파일 스캔):
sonar integrate git --hook pre-commit
Pre-push hook (푸시 전 커밋된 파일 스캔):
sonar integrate git --hook pre-push
CI/CD 또는 자동화용 (비대화형 모드):
sonar integrate git --hook pre-commit --non-interactive
GitHub Copilot CLI 통합
이 훅은 이 장치의 모든 Copilot CLI 세션에 적용됩니다:
sonar auth login
sonar integrate copilot
이를 통해 다음 기능이 설치됩니다:
- 비밀 정보 스캔을 위한 Pre-tool-use hook — 하드코딩된 자격 증명(credentials)이 LLM 제공업체로 전송되는 것을 방지합니다.
- SonarQube Agentic Analysis 통합 — 워크플로우 내에서 서버 측 코드 품질 분석을 수행합니다.
- Model Context Protocol (MCP) 서버 — Copilot에서 SonarQube 데이터에 직접 접근할 수 있습니다.
예시 출력(Example Outputs)
비밀 정보 스캔(Scanning for Secrets)
$ sonar analyze secrets src/config.ts
sonar-secrets 2.43.0.11106 is already installed (latest)
Sonar Secrets CLI - BETA (2.43.0.11106)
...
종료 코드(Exit codes): 비밀 정보가 발견되지 않은 경우 0, 하나 이상 발견된 경우 51입니다.
이슈 목록화(Listing Issues)
sonar list issues는 기본적으로 JSON을 출력하며, 사람이 읽기 쉬운 보기(human-readable view)를 보려면 --format table을 전달하십시오.
$ sonar list issues --project my-org_my-app --severities CRITICAL,BLOCKER --page-size 3 --format table
SEVERITY | RULE | MESSAGE | FILE
-------------------------------------------------------------------------------------------------------------------------
...
로컬 변경 사항 분석(Analyzing Local Changes)
$ sonar analyze
SonarQube Agentic Analysis: no files in the change set to analyze.
프로젝트가 SonarQube Cloud Agentic Analysis용으로 구성되어 있고, 스테이징된 변경 사항(staged changes)이 있는 경우, 분석기는 해당 변경 세트에서 도입된 새로운 이슈를 동일한 text/json 형식으로 보고하며, 이는 --format을 통해 선택할 수 있습니다.
AI 코딩 어시스턴트를 위해 --format toon을 사용하십시오. 이는 동일한 JSON 페이로드의 토큰 효율적인 YAML 기반 인코딩입니다:
$ sonar list issues --project my-org_my-app --severities BLOCKER --page-size 1 --format toon
total: 88
p: 1
...
이 형식은 LLM의 파싱을 위해 설계되었으며 Claude Code, GitHub Copilot CLI, Codex, Cursor, Antigravity, OpenCode, Devin, Pi 또는 사용자 지정 AI 워크플로우와 함께 사용될 수 있습니다.
문제 해결(Troubleshooting)
"Project key not found"
증상: Error: Project 'my-project' not found
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
원인 (Cause): 프로젝트 디스플레이 이름 대신 프로젝트 키를 사용함.
해결책 (Solution): sonar list projects의 JSON 출력에서 정확한 프로젝트 키를 사용하세요:
sonar list projects -q my-project
"문제 없음(No issues found)"이 표시되지만 SonarQube 웹 UI에 문제는 존재함
원인 (Cause): 프로젝트가 아직 스캔되지 않았거나, 잘못된 브랜치를 확인하고 있음.
해결책 (Solution):
- SonarQube에서 최소한 한 번 완료된 스캔이 있는지 확인하세요.
- 올바른 조직(organization)에 인증되었는지 확인하세요:
- 브랜치별 문제의 경우, 해당 브랜치를 지정하세요:
sonar list issues --project my-org_my-app --branch feature-xyz
"인증 실패(Authentication failed)" 또는 토큰 오류
증상 (Symptom): Error: Invalid token이 발생하거나 브라우저 인증에 실패함.
해결책 (Solution): 토큰 기반 인증을 사용하세요:
