# Sonatype IQ CLI

The Sonatype IQ Command Line Interface (CLI) is the multi-tool for performing a Lifecycle Analysis. Evaluations of your applications are either run manually or automatically using the CLI in many environments.

## Release Notes

### Version 2.13.1 (July 22, 2026)
- Maintenance release

### Version 2.13.0 (July 08, 2026)
- Introduced granular exit codes
- Added a new `-av/--application-version` parameter that can be used for binary scan in combination with the `compliance` stage
- Removed support for the Ubuntu-based Docker image

### Version 2.12.1 (June 04, 2026)
- Maintenance release

### Version 2.12.0 (June 03, 2026)
- Added support for reachability analysis evidence
- Added support for PNPM workspaces
- Improved scanning of Red Hat-based Docker images
- Improved Go application scanning by excluding `go.sum` files from non-production directories

### Version 2.11.1 (May 14, 2026)
- Maintenance release

### Version 2.11.0 (May 06, 2026)
- Added support for .NET reachability analysis

### Version 2.10.0 (April 08, 2026)
- Added support for zstd-compressed Docker image layers
- Updated the default scanner mode to Sonatype Container Scanner
- Fixed an issue with memory handling during container scanning

### Version 2.9.0 (March 06, 2026)
- Added support for the Centralized CI configuration

### Version 2.8.5 (February 06, 2026)
- OS-specific CLI bundles now include Java 21
- Alpine-based Docker images for ARM (aarch64) are now available

### Version 2.8.4 (January 06, 2026)
- Fixed an issue where local Sonatype Container scans failed due to unnecessary remote requests

### Version 2.8.3 (December 17, 2025)
- Maintenance release

### Version 2.8.2 (December 05, 2025)
- Fixed an edge case where scans failed for npm projects

### Version 2.8.1 (December 04, 2025)
- Added support for Bearer authorization in Sonatype Container scanning

### Version 2.8.0 (November 21, 2025)
- Added support for JavaScript reachability analysis

### Version 2.7.0 (November 07, 2025)
- Added support for npm workspaces
- Fixed an issue where the “Legacy Scanner Used” banner was incorrectly displayed in IQ
- Improved scan performance for `pnpm-lock.yaml` files
- Improved error logging to present more details

### Version 2.6.0 (October 09, 2025)
- Added support for Sonatype Container Scanner
- Added support for Docker Client v28 in Docker Image Analysis
- Fixed an issue that prevented `java.net.useSystemProxies=true` from working as expected
- Added support for scanning pnpm-lock.yaml v9 manifest files

### Version 2.5.1 (September 11, 2025)
- Added support for analyzing Java 25 bytecode

### Version 2.5.0 (August 15, 2025)
- Added support for analyzing Java 23 and Java 24 bytecode

### Version 2.4.6 (August 06, 2025)
- Maintenance release

### Version 2.4.5 (July 30, 2025)
- Maintenance release

### Version 2.4.4 (July 10, 2025)
- Updated the default method-selection strategy for reachability analysis to CONCRETE: it now includes all non-abstract/synthetic methods from non-interface/annotation classes

### Version 2.4.3 (June 12, 2025)
- Fixed issue that prevented reachability analysis from successfully running against `.tar` files

### Version 2.4.2 (May 09, 2025)
- Added support for APT and YUM packages on Linux for Intel (x86-64) architecture

### Version 2.4.1 (April 29, 2025)
- Fixed a Reachability Analysis compatibility issue with previous IQ Server versions

### Version 2.4.0 (April 22, 2025)
- Added new reachability parameters (`-ra` and `-rn`) to replace the previous options (`-c` and `-cn`)
- Fixed an issue where broken symlink errors were not ignored when `ignore-scanning-errors` was set to true

### Version 2.3.0 (April 02, 2025)
- Added support for Homebrew packages on macOS for both Apple Silicon (AArch64) and Intel (x86-64) architectures

### Version 2.2.0 (March 05, 2025)
- Added both Priorities and Report URLs to Scan Results Summaries

### Version 2.1.1 (February 14, 2025)
- Fixed an issue that prevented components from being identified when scanning a pom.xml with missing nested component values

### Version 2.1.0 (February 05, 2025)
- Removed sensitive information (i.e. authorization cookies) and low-level jGit internal logs from the debug output
- Fixed an issue where scanning pyproject.toml and poetry.lock files resulted in an empty report with no components detected for Poetry 2

### Version 2.0.0 (January 09, 2025)
- Improved handling for `Cargo.lock` and `Cargo.toml` files now allows full exploration of Cargo project dependency trees in Lifecycle
- Added support for `pipfile.lock` files
- Fixed a bug related to `pnpm-lock.yaml` files found inside archives
- Added branch name collection when the CLI is run in a Git repository context
- Fixed an issue for an edge case where Sonatype Container Security failed to detect the container registry

### Version 1.185.0 (December 11, 2024)
- Added support for customizing container scans to include only OS components via the `NEXUS_CONTAINER_INCLUDE_ONLY_OS_COMPONENTS` environment variable

### Version 1.184.0 (November 08, 2024)
- Removed the mount path requirement for Sonatype Container Security
- Added support for files ending with the pattern .cdx.json

### Version 1.183.0 (October 10, 2024)
- Maintenance release

### Version 1.182.0 (September 04, 2024)
- Added support for customizing the container scan runtime via the `NEXUS_CONTAINER_SCANNING_RUNTIME` environmental variable
- Added support for customizing the container scan socket mapping via the `NEXUS_CONTAINER_SOCKET_MAPPING` environmental variable

### Version 1.181.0 (August 20, 2024)
- Updated internal dependencies to ensure compatibility with Lifecycle 181

### Version 1.180.0 (August 8, 2024)
- Updated internal dependencies to ensure compatibility with Lifecycle 180
- Added support for analyzing Java 21 and Java 22 bytecode
- Going forward Sonatype CLI requires Java 17 to run

### Version 1.162.0 (June 2023)
- Notable bug fix
  - Scan targets containing folder names with spaces are now handled correctly

### Version 1.158.0 (March 2023)
- Updates to Nexus Container Scanning with Nexus IQ CLI
  - Scanning remote images does not require providing environmental variables if the image is public

### Version 1.152.0 (January 2023)
- Introduced call flow analysis in Java (or any JVM language) binaries found in the scan targets to find method signatures that trigger a security vulnerability

### Version 1.150.0 (November 2022)
- Updates to Nexus Container Scanning with Nexus IQ CLI
  - Scanning local images does not require providing environmental variables
  - To scan remote images, the user will now have to provide only these variables: `NEXUS_CONTAINER_SCANNING_REGISTRY_USER` and `NEXUS_CONTAINER_SCANNING_REGISTRY_PASSWORD`
- Evaluations exit with a non-zero if there are any scanning errors

### Version 1.145.0 (October 2022)
- Notable bug fix
  - Releases 142 and above fix a bug where a manifest scan processed pom.xml files inside a META-INF directory. Files in this directory, in most cases (specifically for uber/shaded archives), do not represent the manifest file for the target application to be scanned. All pom.xml files inside a META-INF directory from release 142 and above are now ignored during a manifest scan

### Version 1.143.0 (September 2022)
- CycloneDX REST API Improvements
- Improved support for evaluating Java 18 applications and components
- Improvements to Nexus IQ CLI for auto-creating new applications

### Version 1.133.0 (March 2022)
- Dependency Information for CycloneDX SBOM scans

### Version 1.132.0 (January 2022)
- Bug fix for false positives in docker image scans

### Version 1.130.0 (December 2021)
- Update logback library version to remediate a low/moderate vulnerability (Nexus IQ Server does not use log4j)
- Cran and Cargo matching improvements
- Conda matching improvements

### Version 1.125.0 (October 2021)
- Conan Matching Improvements
  - Conan data and matching have been improved for both Lifecycle and Firewall
- Dependency Information Improvements for NPM
  - NPM Dependency Information detection has been improved to display more accurate results
- Added support for analyzing Java 17 bytecode

### Version 1.123.0 (September 2021)
- Fixed an issue with some NPM scans that were causing IQ Server 122 evaluations to fail when reading dependency information

### Version 1.122.0 (September 2021)
- Dependency Information for NPM
  - NPM project scans with manifests allow the displaying of dependency information for NPM components (Direct and Transitive)

### Version 1.120.0 (July 2021)
- Added support for container scanning via Nexus Container

### Version 1.119.0 (July 2021)
- SBOM Improvements and Bug Fixes:
  - CycloneDX SBOM scans have been improved to display better results in the report and some bugs have been fixed as well

### Version 1.118.0 (June 2021)
- Swift Application Analysis:
  - IQ Server can now be used to evaluate policies against components from the dependency file of a Swift application

### Version 1.117.0 (June 2021)
- Support for CycloneDX 1.3
  - CycloneDX Application Analysis has been extended to support the schema version CycloneDX 1.3 for XML format

### Version 1.116.0 (June 2021)
- Improvements to Python Application Analysis:
  - IQ Server now supports evaluating policies against Python components defined in poetry.lock files

### Version 1.114.0 (May 2021)
- Support for CycloneDX 1.2
  - CycloneDX Application Analysis has been extended to support the schema version CycloneDX 1.2 for XML format

### Version 1.107.0 (March 2021)
- Java Manifest Application Analysis
  - IQ Server now supports evaluating policies against Java components in pom.xml and build.gradle files

### Version 1.106.0 (March 2021)
- Improvements to manifest analysis:
  - Updated CLI scanner to exclude development dependencies when scanning package-lock.json files
  - Updated CLI scanner to parse package-lock.json files stored inside an archive
  - Fixed parsing errors when scanning yarn.lock and \*.csproj files

### Version 1.105.0 (Feb 2021)
- Fixed initialization error in NuGet manifest scanning

### Version 1.104.0 (Jan 2021)
- Application analysis of components for:
  - NPM, as defined in yarn.lock, pnpm-lock.yaml, package-lock.json, and npm-shrinkwrap.json files
  - NuGet, as defined in .csproj and packages.config files

### Version 1.103.0 (Dec 2020)
- Added support for analyzing Java 14 and 15 bytecode

### Version 1.101.0 (Nov 2020)
- Nexus IQ CLI no longer supports Lifecycle XC. IQ Server now has native support for all languages that were supported in Lifecycle XC

### Version 1.98.0 (Sep 2020)
- Application analysis of components for:
  - Go components defined in a Gopkg.lock

### Version 1.97.0 (Aug 2020)
- Application analysis of components for:
  - C/C++ components defined in a conaninfo.txt file
  - Go components defined in a go.list file

### Version 1.94.0 (Jun 2020)
- Now released in sync with Nexus IQ Server releases (which may or may not include updates relevant to this docker image’s release)
- Application analysis of components for:
  - C/C++ conanfile.py Files
  - Yum
  - Alpine
  - Debian
  - Drupal
  - R (CRAN)
  - Rust (Cargo)

### Version 1.88.0 (Mar 2020)
- Application analysis of components for:
  - Swift/Objective-C CocoaPods
  - Conda

### Version 1.87.0 (Mar 2020)
- Identify components based on SHA-1 value (content hash)
- Application analysis of components for:
  - C/C++ Conan
  - PHP Composer
  - RubyGems
  - CycloneDX application analysis extended to support submitting component vulnerabilities

## Compatibility

| CLI Version | IQ Server Version | Java Runtime |
| --- | --- | --- |
| 1.180.0 to latest | 87 to latest | JDK 17 to latest |
| 1.87.0 to 1.179.0 | 87 to latest | JDK 8 to JDK 11 |

**Note**

For detailed information on feature availability in each CLI version, please review the [IQ CLI Release Notes](https://help.sonatype.com/en/sonatype-iq-cli.html#release-notes-162517).

## Getting started with the Sonatype IQ CLI

You will need to perform a few tasks to run a Lifecycle analysis using the CLI.

1. Set up an environment to analyze.
2. Set credentials to use with the CLI.
3. Prepare an application in Lifecycle.

### Set up an environment to analyze

#### IQ CLI for Java

**Download latest version for Java:**

[nexus-iq-cli-latest.jar](https://download.sonatype.com/clm/scanner/latest.jar) ( [ASC](https://download.sonatype.com/clm/scanner/latest.jar.asc), [SHA1](https://download.sonatype.com/clm/scanner/latest.jar.sha1))

The CLI JAR is a Java application that requires a Java Virtual Machine (JVM) in the environment you want to perform the analysis.

#### IQ CLI for Docker

The Sonatype IQ CLI and related documentation is also available as a Docker image on [DockerHub](https://hub.docker.com/r/sonatype/nexus-iq-cli). The PKI option is not supported by the Docker image.

##### Supported Docker image platforms

The `sonatype/nexus-iq-cli` Docker image is published as a multi-platform Linux image. Current Sonatype-published `latest`, `latest-alpine`, current versioned, and current versioned `-alpine` tags support the following platforms:

| Platform | Description |
| --- | --- |
| `linux/amd64` | Linux on x86-64 / Intel / AMD 64-bit systems |
| `linux/arm64` | Linux on ARM64 / AArch64 systems |

- These are Linux container images. Windows container images are not published for this image.

- Use current Docker and container runtime versions that support multi-platform images.

- This platform support applies to the Docker image that runs the Sonatype IQ CLI. It does not change the CLI feature matrix or the existing Docker image limitation that PKI authentication is not supported by the Docker image.

```bash
docker pull sonatype/nexus-iq-cli:latest
docker pull --platform linux/arm64 sonatype/nexus-iq-cli:latest
docker pull --platform linux/amd64 sonatype/nexus-iq-cli:latest
```

### CLI Authentication

For automated systems, we recommend passing a [user token](https://help.sonatype.com/en/iq-server-user-tokens.html) instead of a username and password. You may consider configuring a dedicated service account with the minimum access privileges.

The authentication credentials require the `Evaluate applications` permissions for the specific application or organization to perform an analysis. We recommend using the default `Application Evaluator` role for simplicity.

See [Passing CLI parameters from a file](https://help.sonatype.com/en/passing-cli-parameters-from-a-file.html) for details.

### Evaluating an Application

The CLI will need an application configured in the Lifecycle server to determine which policy to use and to associate the finished scan report. Applications may be added beforehand or during evaluation using the [Using Automatic application creation with the CLI](https://help.sonatype.com/en/automatic-application-with-the-cli.html) feature.

Applications may be analyzed as a built archive file or a directory (build workspace) containing the application code.

As a Java application, the CLI is started using a java command with the required parameters. The syntax below represents the minimum set of options required to evaluate an application.

#### Example Lifecycle CLI Evaluation

The CLI requires the following parameters to run a scan: the `applicationId`, the `Lifecycle URL`, and `credentials` with permissions to analyze this application.

```bash
java -jar [sonatype-cli] -a [username:password] -i [--application-id] -s [--server-url] [scan-target]
```

Example command

```bash
java -jar nexus-iq-cli*.jar \ 
  -a username:password \ 
  -i sandbox-application \ 
  -s http://localhost:8070 \ 
  ./sample-application.zip
```

Access the CLI help by running it without parameters

```bash
java -jar ./nexus-iq-cli*.jar
```

## CLI parameters

### sonatype-cli

The path to the Sonatype CLI jar file or native binary.

### -a, --authentication

Provide credentials in the following format: `username:password`

### --pki-authentication

Delegate authentication to the JVM environment.

### -i, --application-id

The PublicId for the application. When [Automatic Applications](https://help.sonatype.com/en/automatic-application.html) is enabled and the PublicId has not yet been used, a new application will be created.

### -O, --organization-id

The ID for the organization to which the application belongs. When automatic application creation is enabled and the application does not exist, it will be created under the organization having the provided organization ID.

### -s, --server-url

The location of your Lifecycle server (e.g. [http://localhost:8070](http://localhost:8070/)).

### Scan-Target

Path to specific files, directory, or Docker image. Include one or more scan targets at the end of the command.

### Additional parameters

Additional options to use in evaluating applications with the Sonatype CLI.

### -t, --stage

Specify the development lifecycle stage for the analysis. Defaults to the `build` stage

### -r, --result-file

Send the output to a specific file path as a JSON data object.

### -m, --metadata-file

Specify the file path providing a JSON object containing the commit hash for the SCM integrations.

```json
{"commitHash": "<git-commit-hash>"}
```

### --module-exclude

Specify module files to ignore via Apache Ant-styled patterns. Repeat the option for multiple specifications.

```bash
**/sonatype-clm/module.xml
```

### -w, --fail-on-policy-warnings

Causes a failure of the evaluation if any warnings are encountered.

### -e, --ignore-system-errors

Ignore system errors (e.g. IO, Network, server, etc.) when running on continuous integration servers to avoid unintentional build failures.

### -E, --ignore-scanning-errors

Ignore scanning errors (e.g. invalid files, inaccessible files, etc) when the code base contains invalid files for testing purposes. Scanning these files may cause unintentional build failures.

### -X, --debug

Enables debug logging for troubleshooting. Use with caution as this log may expose sensitive information.

### -h, --help

Output help context for CLI.

### -v, --version

Output version of the CLI

### -k, --keep-scan-file

Retain the temporary scan file normally deleted at the end of the scan.

### -o

Set the directory to write scan output files.

### Proxy parameters

### -p, --proxy

Specify a proxy to use when connecting to the Lifecycle server. This property is set using the format <host\[:port\]>,
otherwise, the CLI uses the default HTTP proxy for the JVM.

### -U, --proxy-user

Specify proxy credentials in the following format: `<username:password>`

### Reachability Analysis parameters

See [Reachability Analysis with Sonatype CLI](https://help.sonatype.com/en/reachability-analysis-cli.html) for how to enable Reachability in Java/JVM builds.

## Evaluation results

When the Sonatype CLI evaluation succeeds, the output includes a summary and a link to the scan report. If the target IQ server supports priorities URLs (with both `developmentDashboardEnabled` and `prioritizedFindingsReportEnabled` set), a link to the priorities URL is also provided.

## Centralized CI configuration

To centrally manage supported CI evaluation settings for Sonatype IQ CLI through the Lifecycle organization and application hierarchy, see the [CI Configuration REST API](https://help.sonatype.com/en/ci-configuration-rest-api.html).

## Exit Codes

The Sonatype IQ CLI emits the following exit codes:

| Exit Code | Description |
| --- | --- |
| 0 | Success |
| 1 | Policy violation |
| 2 | Scanning error |
| 3 | Reachability error |
| 4 | Configuration error |
| 5 | Connectivity error |
| 6 | Local I/O error |
| 7 | Authentication error |
| 99 | Internal error |