User guide

User guide

Getting started

If you just want to have an idea of what sonarwhal does and you have an updated version of npm (v5.2.0) and Node LTS (v8.9.2) or later you can use the following command:

npx sonarwhal

Alternatively, you can install it locally with:

npm install -g --engine-strict sonarwhal

You can also install it as a devDependency if you prefer not to have it globally.

The next thing that sonarwhal needs is a .sonarwhalrc file. The fastest and easiest way to create one is by using the flag --init:

sonarwhal --init

This command will start a wizard that will ask you a series of questions (e.g.: what connector to use, what formatter, which rules, etc.). Answer them and you will end up with something similar to the following:

"connector": {
"name": "connectorName"
"formatters": ["formatterName"],
"rules": {
"rule1": "error",
"rule2": "warning",
"rule3": "off"
"rulesTimeout": 120000

Then you just have to run the following command to scan a website:


Wait a few seconds and you will get something similar to the following:

Example output for the summary formatter

It might take a few minutes to get some of the results. Some of the rules (e.g.: SSL Labs) can take a few minutes to report the results.

Now that you have your first result, is time to learn a bit more about the different pieces:

Permission issues during installation

If you receive an EACCES error when installing sonarwhal, it is caused by installing packages globally. The recommended solution is to change npm’s default directory and then try again. There have been reports of this issue when installing the dependency canvas-prebuilt throws an EACCES. This issue was resolved adopting the recommended solution. You can find detailed steps on how to change the npm default directory here. According to npm’s documentation, if you have node installed using a package manager like Homebrew or nvm, you may be able to avoid the trouble of messing with the directories and have the correct permissions set up right out of the box. As a result, you won’t experience the error described above even if you install sonarwhal globally.