SonarQube SonarScanner CLI
The SonarScanner CLI is the general-purpose tool that reads your source code and sends the results to SonarQube. It works with almost any language and any build system, which makes it the best starting point when no special plugin exists for your tools.
The Inspector Picture
Think of the scanner as a building inspector. The inspector walks through every room, writes a report, and mails it to the city office. SonarQube plays the city office: it stores the report, grades the building, and tracks repairs.
Your project folder SonarScanner CLI SonarQube Server ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ │ src/ │ ───► │ 1. read settings │ ───► │ receives report │ │ tests/ │ │ 2. analyze files │ │ grades the code │ │ sonar-project. │ │ 3. build report │ │ shows dashboard │ │ properties │ └───────────────────┘ └───────────────────┘ └───────────────────┘
Install the Scanner
- Download the SonarScanner CLI package for your operating system from the Sonar documentation site.
- Unzip the package into a stable folder, such as C:\tools\sonar-scanner or /opt/sonar-scanner.
- Add the bin folder to your PATH variable.
- Open a new terminal and run sonar-scanner -v to confirm the version.
Docker users can skip installation and run the official sonarsource/sonar-scanner-cli image instead.
Create a Token
The scanner proves its identity with a token instead of a password. Tokens can be revoked without changing your login.
- Click your profile icon in SonarQube and open My Account.
- Select the Security tab.
- Enter a token name, choose a type, and click Generate.
- Copy the value immediately, because SonarQube shows it only once.
The Project File
Place a file named sonar-project.properties in the root of your project.
sonar.projectKey=shop-backend sonar.projectName=Shop Backend sonar.projectVersion=1.0 sonar.sources=src sonar.tests=tests sonar.sourceEncoding=UTF-8 sonar.host.url=http://localhost:9000
Key Settings Explained
| Property | Meaning |
|---|---|
| sonar.projectKey | Unique ID of the project on the server |
| sonar.projectName | Friendly name on the dashboard |
| sonar.sources | Folders that hold production code |
| sonar.tests | Folders that hold test code |
| sonar.exclusions | Files the scanner should skip |
| sonar.host.url | Address of the SonarQube server |
Run the Scan
Pass the token on the command line. Never store tokens in files that go into version control.
sonar-scanner -Dsonar.token=YOUR_TOKEN_HERE
The scanner prints progress lines and ends with a link to the finished analysis. Open that link to see the dashboard.
Skip Files You Do Not Own
Generated code, third-party libraries, and build output distort your numbers. Exclude them with wildcard patterns.
sonar.exclusions=**/node_modules/**,**/dist/**,**/*.min.js
Patterns use double stars for any folder depth and single stars for any file name part.
Wait for the Quality Gate
Add one flag to make the scanner pause until SonarQube finishes processing and decides pass or fail.
sonar-scanner -Dsonar.qualitygate.wait=true
A failed gate returns a non-zero exit code. Build servers read that code and stop the pipeline, which blocks weak code from moving forward.
Settings Priority
The scanner reads settings from several places. Command-line values override the project file, and the project file overrides server defaults. This order lets you keep stable values in the file and change one value per run from the terminal.
Troubleshooting
- Not authorized means the token is wrong, expired, or lacks permission for the project.
- Unable to connect means the host URL is wrong or the server is down.
- No files analyzed means sonar.sources points to the wrong folder.
- Out of memory on huge projects calls for a larger limit through the SONAR_SCANNER_OPTS variable.
Quick Recap
Install the scanner, generate a token, describe the project in a properties file, and run one command. The same pattern works on a laptop and on every build server you add later.