CLI Command Reference

This is a reference for the Polaris CLI arguments and usage.

The following are the Polaris CLI commands, options, and switches.

Usage and Syntax

polaris (-h | --help)
polaris (-v | --version)
polaris [options] <command> [<arguments>...]
polaris [--co=<config-option>]... [options] <command> [<arguments>...]
polaris (--test-settings --co=<config-option>...) [options] <command> [<arguments>...]

Description

Invokes the given <command> with the given <arguments>. The supported <arguments> are specific to the given <command> being invoked.

Global Options

Global options for the Polaris CLI apply regardless of the requested command. You can get command line help, specify a configuration file, remove a locally stored access token, or print a version message. The options usually have a short version and a long version.

Table 1. Global Options
Option	Definition
`-c, --configuration-file <file>`	Specifies the configuration file to use. Defaults to polaris.yml in the current working directory. To generate one for you, use setup command. For more information, run `polaris help setup.`
`--co`	Overrides the configuration file for whatever property comes right after it. The property stored in the configuration file is ignored when analysis runs, and the parameter entered on the command line is used. For more information, refer to the help topic Overriding the Configuration File from the CLI.
`-h, --help`	Use this option to display usage information for the Polaris CLI command. Any subsequent options are ignored. For details on a specific command, use `help` (no dashes) followed by the command name. For example, to better understand the capture command, use this command: `$ polaris help capture`
`-i, --invalidate-access-token`	If specified, removes the access token from the local system. This common option cannot be used alone and must be used as part of the Polaris command; for example: `$ polaris -i initialize`
`-p, --persist-config`	Saves configurations to the YML file when they are set in the command line. Must be accompanied by the `--co` command.
`-s, --server-url <url>`	Use this option to specify the Polaris server URL. Using this command line option takes precedence over the `POLARIS_SERVER_URL` environment variable, which in turn takes precedence over the server URL setting in the polaris.yml file.
`-v, --version`	This option displays the current version of the Polaris CLI. As of version 2020.07, the version is automatically included in the console output log files. Running a scan displays the CLI version in the first line of output.
`-w`	When you use the `-w` flag, the Polaris CLI waits for analysis to finish before proceeding with other commands. Always use the `-w` flag when running `polaris analyze` locally.

Help Options

To get help on the options supported for a specific command, use:

polaris help <command>

For example:

polaris help analyze

To get information on all supported commands, use:

polaris help

Table 2. Updating the project name using the -co option
Operating System	Command
Mac, Linux	`polaris --co project.name=\"newProjectname\" analyze`
Windows	`polaris --co project.name=\"newProjectname\" analyze`
Windows (PowerShell)	`polaris --co project.name='\"newProjectname\"' analyze`

Table 3. Updating more than one field in an object
Operating System	Command
Mac, Linux	`polaris --co project='{"branch":"new_branch", "name":"new_name"}' analyze`
Windows	`polaris --co project="{\"branch\":\"new_branch\", \"name\":\"new_name\"}" analyze`
Windows (PowerShell)	`polaris --co project='{\"branch\":\"new_branch\", \"name\":\"new_name\"}' analyze`

Table 4. Updating the configuration file from the command line
Operating System	Command
Mac, Linux	`polaris --persist-config --co project.name=\"newProjectname\" analyze`
Windows	`polaris --persist-config --co project.name=\"newProjectname\" analyze`
Windows (PowerShell)	`polaris --persist-config --co project.name='\"newProjectname\"' analyze`

Command Reference

Table 5. Commands
Command	Description
`analyze`	Analyzes captured artifacts.
`capture`	Invokes the given build command(s) capturing the build source and output. Includes all non-compiled files.
`configure`	Reads and validates the supplied configuration file. If you are not sure how to make a configuration file for Polaris, use the setup life cycle.
`help`	Displays detailed help documentation.
`initialize`	Performs a compatibility check and validates the server status and access token.
`install`	Downloads and installs the required client tools packages from the server. These tools are used to generate the data submitted to the server for analysis.
`prepare`	Performs required additional processing on the captured artifacts before they are analyzed.
`setup`	Generates the configuration file based on the project directory.

Command: analyze

Description:

The analyze command triggers analysis on captured artifacts.

For central mode, this command uploads the capture directory to the Polaris server where the submitted artifacts are analyzed.
For local mode, captured artifacts are analyzed locally.

Assuming you passed the -w flag to wait for the analysis to finish, the Polaris CLI displays a brief summary of the analysis, similar to the following example.

  [INFO] [r56csk01] Coverity - analyze phase took 5m 41.083s.
  Analysis Completed.
  Coverity analysis
  {
   "JobId": "q23ro8dbgl3vv4e4qdabvc4bls",
   "Status": "Success"
  }     Job issue summary
     {
      "IssuesBySeverity": {
       "Critical": 0,
       "High": 0,
       "Medium": 5,
       "Low": 0
      },
      "Total": 5,
      "NewIssues": 1,
      "ClosedIssues": 0,
      "SummaryUrl": "https://dev01.dev.polaris.synopsys.com/projects/67d0f4df-12f2-4dbd-beb9-530a583fdb1c/branches/e8a22884-20a9-4571-a142-50fca02bf6eb"
       }

Table 6. Options and usage for the analyze command
Command	Description
`--coverity-ignore-capture-failure`	Allows Polaris to proceed with the analysis when a capture fails. The option configures Polaris to ignore capture failures from Coverity if at least one file is captured. If nothing is captured, Polaris exits with a capture error. This feature is useful when you decide to proceed with the analysis because some amount of capture failure is not relevant. A failed capture might have enough files to make the results worth reviewing.
`-w, --wait`	Waits for the analysis to complete. It is mandatory to be used with local mode. This flag is optional when using central analysis. In case `-w` is not passed, the CLI concludes the execution by displaying the submitted job ID. When `-w` is passed, the CLI waits for the scan to complete before displaying a short summary of results of completed analysis.
`--upload-local-config`	Uploads the local configuration to the configuration server upon successful capture. Only project administrators are allowed to perform this action. The uploaded configuration will not be enforced by default. To enforce use of the centralized configuration file, change the setting in the Polaris Web Interface.
`[--] [<build-command>...]`	A build command to generate outputs of the build.
`-rp, --run-property`	Creates a property and value that can be used to retrieve a specific run or group of runs from the `/run-properties` endpoint on the Common Objects Service of Polaris API. Properties should be of the format <property_key>=<property_value>. Use up to 50 custom properties within a run; Keys are limited to 128 characters and values to 999 characters. The total length of all custom properties is limited to 1200 characters. Note that run properties are not encrypted, so they shouldn't contain sensitive data. See examples below.

Table 7. Examples for the analyze command
Command	Description
$ `polaris -c polaris.yml analyze -w`	Analyzes a project and waits for the analysis to complete.
`$ polaris -c polaris.yml capture`	Captures artifacts for analysis.
`$ polaris analyze --coverity-ignore-capture-failure`	Ignores Coverity capture failures and proceeds with the analysis.
$ `polaris analyze --upload-local-config`	Uploads the local configuration to the configuration server upon successful capture.
`$ polaris analyze -- mvn clean install`	The build command used in the capture command for Maven projects.
`$ polaris analyze -w -rp pipeline=DevOps3`	The -rp option creates a key called "pipeline" with a string value of "DevOps3".
`$ polaris analyze -w --run-property language=Java --run-property language=.net`	The --run-property option creates a key called `"language"` with a list value of `["Java", ".net"]`. (Note that You can use both string values and list values with different properties in the same run.)

Command: capture

Description:

The capture command goes with the project's build to capture source files for analysis.

The capture command:

Determines what is analyzed based on the configuration file.
Executes a file system capture.
Runs a build.
Saves data to the work directory.

The default working directory is .synopsys/polaris in your project directory. You can change this with a captureDir entry in the configuration file.

For build capture, this command:

Runs a build.
Attempts to clean up the project, using the cleanCommands defined in the configuration file.
Runs a build as defined by buildCommands in the configuration file.
As the build progresses, Polaris extracts the data it needs and saves it in the working directory.

You can override the build command at the command line. Anything after a double dash is used as the build command.

Table 8. Options for the capture command
Command	Description
`--coverity-ignore-capture-failure`	Allows Polaris to proceed to analysis when a capture fails. This option configures Polaris to ignore any capture failures from Coverity if at least one file is captured; if nothing is captured, Polaris exits with a capture error. This feature is useful when you decide to proceed to analysis because some amount of capture failure is not relevant. A failed capture might have enough files to make the results worth reviewing.
`[--] [<build-command>...]`	A build command to generate outputs of the build.

Table 9. Examples for the capture command
Command	Description
`$polaris capture --coverity-ignore-capture-failure`	Ignores Coverity capture failures and proceeds for analysis.
`$polaris capture -- mvn clean install`	For Maven projects, the build command to be used with the `capture` command, regardless of what's defined in the configuration file.

Command: configure

Description:

The configure command reads and validates the supplied configuration file. If you are not sure how to make a configuration file for Polaris, use the setup life cycle.

Options: None.

Table 10. Examples for the configure command
Command	Description
`polaris configure`	Configuration.
`polaris -c polaris.yml setup`	Generates a configuration file.
`polaris -c polaris.yml analyze --upload-local-config -w`	Centralizes project configuration as a project administrator.

Command: initialize

Description:

The initialize command:

Performs a compatibility check.
Validates the server status and access token.

Options:

None.

Table 11. Examples for the initialize command
Command	Description
`polaris initialize`	Performs a compatibility check, then validates the server status and access token.
`polaris -i initialize`	Invalidates an existing access token.
`polaris -s <url> initialize`	Passes the server instance to use.

Command: install

Description:

The install command downloads and installs the required client tools packages from the server. These tools are used to generate the data submitted to the server for analysis.

Options: None.

Table 12. Examples for the install command
Command	Description
`polaris install`	Downloads and installs the required client tools packages from the server.

Command: prepare

Description:

The prepare command performs required additional processing on the captured artifacts before they are analyzed.

Table 13. Options for the prepare command
Command	Description
`--coverity-ignore-capture-failure`	Allows Polaris to proceed to analysis when a capture fails. This option configures Polaris to ignore any capture failures from Coverity if at least one file is captured; if nothing is captured, Polaris exits with a capture error. This feature is useful when you decide to proceed to analysis because some amount of capture failure is not relevant. A failed capture might have enough files to make the results worth reviewing.
`[--] [<build-command>...]`	A build command to generate outputs of the build.

Table 14. Examples for the prepare command
Command	Description
`$polaris prepare --coverity-ignore-capture-failure`	Ignores Coverity capture failures and proceeds for analysis.
`$polaris prepare -- mvn clean install`	For Maven projects, the build command used in the capture command.

Command: setup

Description:

The setup command automatically creates a configuration based on the project directory contents.

Project settings are generated based on SCM information if available. Alternatively, it is generated using the project directory name when the project is not a part of an SCM. SCM inference is subjected to the availability of respective SCM binaries in $PATH. Currently, only git and svn are supported.

The location of the project directory is inferred from the location of the output configuration file given by the -c option. This defaults to polaris.yml in the current directory.

Build settings are generated based on the available build system files such as pom.xml and build.xml.

For file system capture settings, all the supported non-compiled artifacts are configured for capture.

It is recommended that you review and change the generated configuration as per your project requirements.

Steps for using the setup lifecycle:

1. In the CLI, navigate to the project directory.

2. Invoke setup with the output configuration file path: polaris -c config.yml setup

3. Enter the server URL if prompted.

4. Enter the access token if prompted.

5. Review the generated configuration file.

Table 15. Options for the setup command
Command	Description
`-b <build_command_spec>, --build-command <build_command_spec>`	A build command to generate outputs of the build. The format is <build_type>=<build_command> where type is a supported build system. Note that <build_command> is assumed to be whitespace delimited.
`-c <clean_command_spec>, --clean-command <clean_command_spec>`	A clean command to generate outputs of the build. The format is <build_type>=<clean_command> where type is a supported build system. Note that <clean_command> is assumed to be whitespace delimited.
`-f <artifacts_spec>, --artifacts <artifacts_spec>`	A collection of non-compiled artifacts to analyze of the form <artifact_type>=<include> where <artifact_type> is a supported non-compiled artifact type and <include> is specified as "<operator>: <argument>". Operator is one of file, directory, or include Regex and <argument> is the operator specified argument; for example, a path if <operator> is directory.
`-p <name>, --project-name <name>`	The name to assign to the project.
`-t <tools_spec>, --tools <tools_spec>`	A comma-separated list of tool names to be installed with the latest version. If a tool has subtools, each subtool must be qualified with the tool name followed by a ':' character; for example, coverity.
`--analysis-mode <mode>`	An option to allow you to configure Coverity analysis mode with the setup command option.
`--project-property <property_spec>`	An option to define the custom project properties. The properties must be of the format <property_key>=<property_value>. A maximum of five properties can be added to a project.

Table 16. Examples for the setup command
Command	Description
`$ polaris setup --clean-command shell="make -f win32/Makefile.gcc clean"`	Specifies that make `-f win32/Makefile.gcc clean` must be run in a shell to clean the project.
`$ polaris setup --build-command shell="make -f win32/Makefile.gcc"`	Specifies that make `-f win32/Makefile.gcc` must be run in a shell to build the project.
`$ polaris setup -f "javascript=directory: extjs" -f "python=directory: pysrc"`	Specifies that JavaScript files in the extjs directory must be included in the analysis, as well as Python files in pysrc.
`$ polaris setup -p test-project`	Assigns the name test-project to the project.
`$ polaris setup --analysis-mode local`	Specifies that local mode is used for analysis.
`polaris -v`	Displays the version of the Polaris CLI.