Quickstart

This guide installs scanoss-cli, scans a project, and turns the result into a CycloneDX SBOM. You need:

a SCANOSS API key (see API keys and authentication)
a project directory to scan
jq, to read the JSON output (optional, but used in the examples)

Install scanoss-cli

Download the prebuilt binary for your platform from the releases page and put it on your PATH. For Linux on x86-64:

curl -sSLO https://github.com/scanoss/scanoss.go/releases/download/v0.9.0/scanoss-cli-linux-amd64.tar.gz
tar xzf scanoss-cli-linux-amd64.tar.gz scanoss-cli
sudo mv scanoss-cli /usr/local/bin/
scanoss-cli --version

Each release has archives for Linux (amd64, arm64, armv7), macOS (darwin-amd64, darwin-arm64), and Windows (windows-amd64.zip, windows-arm64.zip). If you have Go 1.25 or later, you can install with Go instead:

go install github.com/scanoss/scanoss.go/cmd/scanoss-cli@latest

For Docker and other options, see Installation.

Provide your API key

export SCANOSS_API_KEY="<your-key>"

To keep the key between shell sessions, store it once with scanoss-cli config set api-key "<your-key>" instead.

Scan the project

cd my-project
scanoss-cli scan . --include licenses,vulns --output results.json

The CLI fingerprints every file locally, uploads only the fingerprints, and waits for the result. Progress and the scan ID go to stderr. The result goes to results.json.--include adds optional data to the result. licenses adds the licences of each component, and vulns adds known vulnerabilities. Add deps to also list the dependencies declared in your manifest files.

Read the result

results.json is the SCANOSS raw inventory. This is an abbreviated example of its shape:

{
  "schema_version": "2.0",
  "metadata": { "tool": "scanoss", "tool_version": "v0.9.0" },
  "components": [
    {
      "purl": "pkg:github/madler/zlib",
      "scope": "detected",
      "name": "zlib",
      "vendor": "madler",
      "version": "1.2.11",
      "licenses": [{ "id": "Zlib" }],
      "evidence": [
        { "path": "third_party/zlib/inflate.c", "match_type": "file" }
      ]
    }
  ],
  "vulnerabilities": [
    {
      "id": "CVE-2022-37434",
      "severity": "CRITICAL",
      "source": "NVD",
      "purls": ["pkg:github/madler/zlib@1.2.11"]
    }
  ]
}

Field	Meaning
`components[]`	One entry per component, identified by its PURL and version.
`scope`	`detected`: found by matching your files. `declared`: listed in a manifest (only with `--include deps`).
`evidence[]`	Where the component was found. `match_type` is `file` (a whole file matches), `snippet` (part of a file matches), or `declared` (a manifest entry).
`licenses[]`	SPDX licence IDs for the component (with `--include licenses`).
`vulnerabilities[]`	Known vulnerabilities, linked to components through `purls` (with `--include vulns`).

Summarise it with jq:

# Components found, with version and licences
jq -r '.components[] | "\(.purl)@\(.version // "?")  \([.licenses[]?.id] | join(","))"' results.json

# Vulnerabilities by severity
jq -r '.vulnerabilities[]? | "\(.severity // "unknown")  \(.id)  \(.purls // [] | join(","))"' results.json

An empty components list means no open source was matched.

Generate an SBOM

Convert the inventory you already have. The conversion runs offline and does not scan again:

scanoss-cli sbom results.json --format cyclonedx --output sbom.cdx.json
scanoss-cli sbom results.json --format spdx --output sbom.spdx.json

CycloneDX 1.7 keeps the vulnerabilities. SPDX 2.3 has no vulnerability model, so the CLI leaves them out of the SPDX file and warns you.

Exit codes

scanoss-cli exits 0 when a command completes, whatever it found, and 1 when the command fails. A missing API key, an unreachable API, an invalid flag, or an output file that cannot be written all cause exit code 1. Findings never change the exit code. To fail a build on findings, check the JSON output, as the Recipes show.

Next steps

Recipes show how to scan every pull request, gate on licences and vulnerabilities, publish release SBOMs, and more.
Scanning your project covers every scan flag, file skipping, and BOM rules.
Output formats describes the raw, SPDX, and CycloneDX formats in detail.

Get started

Recipes

CLI reference

API reference

Self-hosting & knowledge base

Exit codes

Next steps

​Exit codes

​Next steps

Exit codes

Next steps