> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scanoss.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install scanoss-cli, scan a project, read the result, and generate an SBOM in under five minutes.

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](/en/latest/developer-tools/authentication))
* a project directory to scan
* [`jq`](https://jqlang.org/), to read the JSON output (optional, but used in the examples)

<Steps>
  <Step title="Install scanoss-cli">
    Download the prebuilt binary for your platform from the
    [releases page](https://github.com/scanoss/scanoss.go/releases) and put it on your `PATH`.
    For Linux on x86-64:

    ```bash theme={null}
    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:

    ```bash theme={null}
    go install github.com/scanoss/scanoss.go/cmd/scanoss-cli@latest
    ```

    For Docker and other options, see [Installation](/en/latest/cli/scanoss-go/installation).
  </Step>

  <Step title="Provide your API key">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Scan the project">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Read the result">
    `results.json` is the SCANOSS raw inventory. This is an abbreviated example of its shape:

    ```json theme={null}
    {
      "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`:

    ```bash theme={null}
    # 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.
  </Step>

  <Step title="Generate an SBOM">
    Convert the inventory you already have. The conversion runs offline and does not scan again:

    ```bash theme={null}
    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.
  </Step>
</Steps>

## 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](/en/latest/developer-tools/recipes) show.

## Next steps

* [Recipes](/en/latest/developer-tools/recipes) show how to scan every pull request, gate on
  licences and vulnerabilities, publish release SBOMs, and more.
* [Scanning your project](/en/latest/cli/scanoss-go/scanning-your-project) covers every scan flag,
  file skipping, and BOM rules.
* [Output formats](/en/latest/cli/scanoss-go/output-formats) describes the raw, SPDX, and CycloneDX
  formats in detail.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.