Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 37 ยท Scanning and Integrations

The Scanner Command Line

Learn the SonarScanner command line: installation, the core analysis properties, property precedence, environment variables, multi-module projects and verbose debugging.

The SonarScanner is the generic command-line tool that analyzes a project and uploads the report. It is the right choice for languages without a build-tool plugin (Python, JavaScript, TypeScript, PHP, Go and many more), and it is also what the specialized scanners wrap. This lesson covers how to install it, the properties that matter and the rules for combining them.

Getting the scanner

Download the SonarScanner CLI for your operating system (the archive bundles a Java runtime in the platform-specific builds), unpack it and add its bin folder to your PATH. Check it with sonar-scanner --version. In CI you normally use an official Docker image or a prepared action rather than installing by hand, which pins the version. JavaScript projects can also use the npm-based scanner package, which runs the same analysis.

The commands in this lesson are read-only examples: the scanner and a server are not available on this site. The runnable parts are stand-ins that build and check commands.

The core properties

Every analysis needs to know where the server is, who you are, what the project is and where its code lives:

  • sonar.host.url: server address.
  • sonar.token: the authentication token (prefer the SONAR_TOKEN environment variable).
  • sonar.projectKey: the unique key; sonar.projectName and sonar.projectVersion are labels.
  • sonar.sources: comma-separated source directories (relative to the project base directory).
  • sonar.tests: directories of test code, so tests are analyzed with test rules and not counted as production code.
  • sonar.sourceEncoding: character encoding, for example UTF-8.
  • sonar.language is rarely needed; the scanner detects languages by file extension.
  • sonar.projectBaseDir: the directory that relative paths resolve against (defaults to where you run the scanner).

Language-specific properties tell analyzers where to find compiled code or reports: sonar.java.binaries, sonar.python.version, sonar.javascript.lcov.reportPaths, sonar.python.coverage.reportPaths and so on. They are the subject of later lessons.

Where properties can come from

The scanner merges several sources. From highest to lowest precedence:

  1. Command-line -Dproperty=value arguments
  2. The sonar-project.properties file in the project (or the file named by -Dproject.settings=)
  3. The scanner's own conf/sonar-scanner.properties (user- or machine-wide settings)
  4. Settings stored on the server (project and global settings from the UI)

Environment variables work for a few special values: SONAR_TOKEN, SONAR_HOST_URL and SONAR_SCANNER_OPTS (JVM options for the scanner, such as -Xmx2g for a big project). Settings that are server-side (such as the quality profile) cannot be overridden from the command line; analysis-time settings can.

Python Merge properties by precedence (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

A complete example

For a Python web service with tests and a coverage report:

PROPERTIES
sonar.projectKey=acme_orders
sonar.projectName=Orders Service
sonar.sources=app
sonar.tests=tests
sonar.python.version=3.12
sonar.python.coverage.reportPaths=coverage.xml
sonar.exclusions=**/migrations/**
sonar.sourceEncoding=UTF-8

Run:

Terminal
sonar-scanner \
  -Dsonar.host.url=http://sonar.internal:9000 \
  -Dsonar.projectVersion=$(git describe --tags --always)

with SONAR_TOKEN already exported. Notice that the server address and version are passed per run, while stable settings stay in the file under version control.

Building commands programmatically

CI scripts often assemble the command from variables. The helper below quotes values safely and refuses to put a token on the command line.

Python Assemble a safe scanner command (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

(The real scanner does accept -Dsonar.token; the stand-in refuses it as a team policy because command-line arguments are visible to other processes on the machine.)

Multi-module projects

A repository with several modules can be described in one properties file with a list of modules and a prefix for each module's own properties:

PROPERTIES
sonar.projectKey=acme_platform
sonar.modules=api,worker
api.sonar.projectBaseDir=services/api
api.sonar.sources=src
worker.sonar.projectBaseDir=services/worker
worker.sonar.sources=src

Newer guidance prefers analyzing modules as separate projects or relying on the build tool's own multi-module support, because the sonar.modules mechanism is deprecated for most scanners. When in doubt, use one sonar.sources list with several folders, or use the build tool plugin (Scanners for Build Tools).

Troubleshooting

  • Add -X (or -Dsonar.verbose=true) to print debug logs: which files are indexed, which properties are effective, which plugins load.
  • Out of memory: raise SONAR_SCANNER_OPTS="-Xmx3g".
  • Files not analyzed: check sonar.sources and sonar.exclusions, and that the extension belongs to a language that is installed.
  • Unexpected "new code": a shallow clone hides history; fetch fully.
  • Unauthorized: wrong token type or missing Execute Analysis.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which source of properties has the highest precedence?

    Arguments passed with -D override the project file, the scanner conf and server settings.
  2. 2. Which property lists the production source directories?

    sonar.sources names the directories to analyze as production code; sonar.tests names test directories.
  3. 3. How do you pass the token safely in CI?

    Secrets belong in the CI secret store and reach the scanner as an environment variable.
  4. 4. What does -X do?

    -X turns on debug output, useful for seeing the effective properties and indexed files.

Summary

  • The SonarScanner CLI analyzes a project and uploads the report; it suits most languages.
  • Core properties: host URL, token, project key, sources, tests, encoding.
  • Precedence: command line, project file, scanner config, then server settings.
  • Keep stable settings in the properties file, per-run values on the command line, secrets in the environment.
  • Use -X and SONAR_SCANNER_OPTS to troubleshoot.

Next: Scanners for Build Tools