# How to use Go analyzer from the command line

This documentation describes how to use PVS\-Studio analyzer for Go via the command line\.

In addition to the CLI, PVS\-Studio offers integration with GoLand and Visual Studio Code\. Learn more from the dedicated documentation:

* [How to use PVS\-Studio extension for Visual Studio Code](https://pvs-studio.com/en/docs/manual/6646/)
* [How to use PVS\-Studio in JetBrains GoLand](https://pvs-studio.com/en/docs/manual/7190/)

## Installation

Information on how to install the analyzer is available in the [dedicated documentation](https://pvs-studio.com/en/docs/manual/7187/)\. 

## How to enter a license

It is necessary to activate the license before using the analyzer\. Learn how to enter the license in the [dedicated documentation](https://pvs-studio.com/en/docs/manual/0046/)\. 

## Quick start

The utility has two modes:

* `analyze` is used to analyze the specified project;
* `suppress` is used to generate a suppress file\.

To view information about all available arguments and flags, run the following commands:

* `pvs-golang --help`
* `pvs-golang analyze --help`
* `pvs-golang suppress --help`

To run a project analysis, use the `analyze` command and specify the path to the directory containing your Go project:

```cpp
pvs-golang analyze /path/to/project
```

After the analysis is finished, the utility saves a report with the `PVS-Studio.json` filename in the current working directory and issues a [return code](https://pvs-studio.com/en/docs/manual/7194/#exit_codes)\.

## Arguments and flags of the 'analyze' mode

The `analyze` mode takes one argument, which is the project directory\.

The flags for the `analyze` mode are listed below\.

### \-\-analysis\-paths, \-P

Specifies how the analyzer behaves on the given paths\. It accepts a string of the following format:

```cpp
(mode=<path>|<glob>)(,mode=<path>|<glob>)*
```

where `mode` defines the analyzer behavior for the specified `<path>` or `<glob>` pattern\. The following modes are available:

* `analyze` is used to analyze files that match the specified path or glob pattern;
* `skip-analysis` is used to exclude from the analysis files that match the specified path or glob pattern\.

By default, the analyzer assumes that every source file should be analyzed \(`analyze=*`\), even when you explicitly pass the flag\. You can specify the flag multiple times, and the analyzer applies the filters in the order you provide them\.

For example, the following configuration excludes the `3rd-party` and `unittests` directories from the analysis while including the `3rd-party/lib1` subdirectory:

```cpp
pvs-golang analyze /path/to/project \
                --analysis-paths "skip-analysis=*/3rd-party/*" \
                --analysis-paths "skip-analysis=*/unittests/*" \
                --analysis-paths "analyze=*/3rd-party/lib1/*"
```

### \-\-source\-files, \-S

Enables file list filtering, enabling the [automatic analysis of commits and pull/merge requests](https://pvs-studio.com/en/docs/manual/0055/) as part of your CI/CD pipeline\.

It takes a file containing a list of paths or glob patterns to analyze\. Specify each path or glob pattern on a separate line, for example:

```cpp
# content of the file
src/source1.go
src/source2.go
```

Relative paths in the file will be expanded to absolute ones relative to the current working directory\.

The example:

```cpp
pvs-golang analyze /path/to/project \
               --source-files fromCommit.txt
```

### \-\-output, \-o

Specifies the path to the analyzer output report\. The file extension you provide as an argument does not affect the report contents\.

To output the report to `stdout`, pass `-` as the argument\.

If you omit this flag, by default, the analyzer writes the report to `PVS-Studio.json` in the current working directory\.

The example: 

```cpp
pvs-golang analyze /path/to/project \
               --output report.json
```

### \-\-analysis\-config, \-c

Enables specifying the analysis configuration via a TOML file\. For more information about this configuration, see the [dedicated documentation](https://pvs-studio.com/en/docs/manual/7193/)\.

By default, the utility looks for the `pvs-settings.toml` file in the directory specified for the analysis\.

The example:

```cpp
cd /path/to/project
pvs-golang analyze . \
               --analysis-config project-settings.toml
```

### \-\-threads, \-j

Specifies the number of analysis threads\. The value should be a non\-negative integer\.

If you specify 0, the analyzer uses all available logical CPU cores\.

If you omit this option, the utility automatically selects the optimal number of threads for the analysis\.

The example:

```cpp
pvs-golang analyze /path/to/project \
               --threads 8
```

### \-\-file\-analysis\-timeout

Specifies the timeout for analyzing a single file\.

The value should use the `XXhYYmZZs` format\.

If you omit this option, the utility stops analyzing a file after ten minutes by default\.

The following example sets the timeout to 30 minutes:

```cpp
pvs-golang analyze /path/to/project \
               --file-analysis-timeout 30m
```

### \-\-source\-tree\-root, \-r

Enables generation of machine\-independent reports\. Specify a directory path, and the analyzer replaces it with the special `|?|` marker in warning locations\. 

The example:

```cpp
pvs-golang analyze /path/to/project \
               --source-tree-root /path/to/project
```

### \-\-rules, \-R

Controls whether diagnostic rules are enabled \(`on`\) or disabled \(`off`\)\.

Accepts a string of the following format:

```cpp
(RULE|RANGE|GROUP)=(on|off)(,(RULE|RANGE|GROUP)=(on|off))*
```

Where:

* `RULE` is a diagnostic rule written in the `Vxxxx` format\. Lists of available diagnostic rules are provided [here](https://pvs-studio.com/en/docs/warnings/#GeneralAnalysisGolang) and [here](https://pvs-studio.com/en/docs/warnings/#OWASPGolang)\.
* `RANGE` is an inclusive range of diagnostic rules specified as `Vxxxx-Vyyyy`, where `xxxx` should be less than `yyyy`\.
* `GROUP` is a group of diagnostic rules\. The following groups are available:
  * `ALL` are all diagnostic rules\.
  * `GA` are general analysis diagnostic rules\.
  * `OWASP` are diagnostic rules for detecting violations of the OWASP ASVS\.

By default, the analyzer enables only the general analysis rule group \(`GA=on`\), even if you explicitly specify this option\. You can specify the flag multiple times, and the analyzer applies the filters in the order you provide them\.

The following example disables all diagnostic rules and enables only rules `V8001` through `V8031`:

```cpp
pvs-golang analyze /path/to/project       \
               --rules ALL=off        \
               --rules V8001-V8031=on
```

### \-\-security\-related\-issues

Enables adding SEC marks to the SAST field of the analyzer warnings\.

The example:

```cpp
pvs-golang analyze /path/to/project \
               --security-related-issues
```

### \-\-indicate\-warnings, \-w

Returns code 1 if the resulting report contains warnings after the analysis completes normally\.

The example:

```cpp
pvs-golang analyze /path/to/project \
               –-indicate-warnings
```

### \-\-no\-noise

Prevents warnings of low certainty level from appearing in the analysis results\.

The example:

```cpp
pvs-golang analyze /path/to/project \
               –-no-noise
```

### \-\-suppress\-files, \-s

The flag sets paths to [suppress files](https://pvs-studio.com/en/docs/manual/0032/)\.

If no flag is specified, by default, the utility implicitly searches for a file named `suppress_file.suppress.json` in the analysis directory\.

You can pass the flag multiple times; the analyzer reads all the specified suppress files\.

The example:

```cpp
pvs-golang analyze /path/to/project \
               --suppress-files /path/to/project/file1.suppress.json \
               --suppress-files /path/to/project/file2.suppress.json
```

### \-\-disable\-license\-expiration\-check

Disables the license expiration check\. Without this flag, if the license expires in less than 30 days, the utility returns code 21 and logs a message\.

The example:

```cpp
pvs-golang analyze /path/to/project \
               --disable-license-expiration-check
```

### \-\-ignore\-analysis\-failures

Enables non\-zero return codes to be ignored for the following non\-critical errors: 

* incomplete code parsing;
* exceeding the analysis timeout;
* incomplete semantic information about the project\.

The example:

```cpp
pvs-golang analyze /path/to/project \
               --ignore-analysis-failures
```

### \-\-license\-file, \-l

Specifies an arbitrary path to the file containing license information\. On Windows, the license should be stored in the [`Settings.xml`](https://pvs-studio.com/en/docs/manual/6653/) file; on Linux/macOS, it should be stored in the [`PVS-Studio.lic`](https://pvs-studio.com/en/docs/manual/0046/) file\.

If the flag is not specified, the utility searches for a license entered using the standard method on [Windows](https://pvs-studio.com/en/docs/manual/0046/#WindowsCLI) or [Linux/macOS](https://pvs-studio.com/en/docs/manual/0046/#UnixLikeCLI) by default\.

The example:

```cpp
pvs-golang analyze /path/to/project \
               --license-file /path/to/project/PVS-Studio.lic
```

## Arguments and flags of the 'suppress' mode

The `suppress` mode suppresses warnings based on the provided analysis reports\. Analyzer warnings that match the suppressed ones will not appear in reports generated during future project checks\. For more information about this mechanism, see the [dedicated documentation](https://pvs-studio.com/en/docs/manual/0032/#ID3C24E2E40C)\.

The mode accepts paths to analysis reports\. By default, suppressed warnings are saved in the current working directory to the `suppress_file.suppress.json` file\. You can change the file location using the corresponding flag described below\. If the file already exists, the utility will add new warnings to it\.

The example:

```cpp
pvs-golang suppress /path/to/project/module1.report.json
                /path/to/project/module2.report.json
```

The flags for the `suppress` mode are listed below\.

### \-\-output, \-o

The path to the resulting suppress file\.

If you pass a directory path as an argument, the utility issues an error\.

If the file already exists and is a suppression file, the utility will add new warnings to it\.

To output the report to `stdout`, pass `-` as the argument\.

The example:

```cpp
pvs-golang suppress /path/to/project/report.json \
                --output /path/to/project/project.suppress.json
```

## Return codes

### The 'analyze' mode

* `0`—the analysis completed successfully\.
* `1`—the analysis completed successfully, but the resulting report contains warnings\. This code is returned only when the `--indicate-warnings` flag is used\.
* `2`—an invalid analyzer configuration specified via the command\-line interface or configuration files was detected\.
* `3`—an unexpected error occurred while running the utility\. This usually indicates errors in the utility itself and is accompanied by additional information printed to `stderr`\. If you encounter this error, please send us the details using the [feedback form](https://pvs-studio.com/en/about-feedback/)\.
* `4`—all files were excluded from analysis\.
* `5`—some files could not be analyzed \(for example, due to a parsing error\)\.
* `6`—some files could not be analyzed because the analysis timed out\.
* `20`—the license has expired\.
* `21`—the license will expire in one month\.
* `22`—the license is missing or invalid\.

### The 'suppress' mode

* `0`—warnings from all provided reports were successfully suppressed\.
* `1`—some warnings from the provided reports were not suppressed due to a non\-critical error\.
* `2`—invalid input data was provided\.
* `3`—an unexpected error occurred while running the utility\. This usually indicates errors in the utility itself and is accompanied by additional information printed to `stderr`\. If you encounter this error, please send us the details using the [feedback form](https://pvs-studio.com/en/about-feedback/)\.