> ## 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.

# Decoration and enrichment

> Query SCANOSS component data by PURL, or refresh an existing inventory's layers without re-scanning.

## Enrich an existing inventory

`enrich` decorates an existing inventory or SBOM with purl-keyed layers through the SCANOSS API.
It needs no source tree, and it doesn't fingerprint or re-scan anything. Because it works only from
PURLs, you can re-run it on the same file, weekly for example, to refresh the layers.

```bash theme={null}
# Refresh vulns/licenses/crypto on a raw inventory (raw in, raw out)
scanoss-cli enrich inv.json --include vulns,licenses,crypto --api-key "$SCANOSS_API_KEY" > enriched.json

# Enrich an SPDX document (spdx in, spdx out)
scanoss-cli enrich sbom.spdx.json --include licenses --api-key "$SCANOSS_API_KEY" > enriched.spdx.json

# Enrich a CycloneDX document and convert to SPDX in one pass
scanoss-cli enrich sbom.cdx.json --include licenses --format spdx --api-key "$SCANOSS_API_KEY" > enriched.spdx.json
```

`enrich` accepts a SCANOSS raw inventory, a CycloneDX document, or an SPDX document, all in JSON,
and detects which one it has from the content. The layers you can pass to `--include` are `vulns`,
`licenses`, `crypto`, and `geo`. `deps` is **not** an enrich layer. Dependency analysis needs
manifests or a source tree, so `--include deps` returns an error here.

By default the output keeps the input's format, so raw stays raw, CycloneDX stays CycloneDX, and
SPDX stays SPDX. Pass `-f, --format` to convert in the same pass. If the output format can't
represent a layer, `enrich` skips that layer up front and prints a notice, following the same rules
as `scan`. `spdx` skips `vulns`, `crypto`, and `geo`, and `cyclonedx` skips `crypto` and `geo`. A
failed service doesn't stop enrichment. `enrich` logs the failure, skips that service, and still
writes a partial result.

`enrich` takes `--include` and `-f, --format` (`raw`, `spdx`, or `cyclonedx`), plus the
[API flags](/en/latest/cli/scanoss-go/scanning-your-project#flags-reference) (`--api-url`,
`--api-key`, `--proxy`, `--ca-cert`, `--ignore-cert-errors`, `-o, --output`).

## Dependencies

`dependencies` has two modes. Local mode parses the manifests under a path. API mode looks up one
component by PURL:

```bash theme={null}
# Local mode: parse manifests under a path and query the API
scanoss-cli dependencies ./my-project --extract-local --output deps.json

# API mode: direct dependencies of a component
scanoss-cli dependencies --purl 'pkg:github/scanoss/engine' --requirement '5.4.7' \
  --api-key "$SCANOSS_API_KEY"

# API mode: transitive dependencies, custom depth/limit
scanoss-cli dependencies --purl 'pkg:github/scanoss/engine' --requirement '5.4.7' --transient \
  --depth 5 --limit 20 --api-key "$SCANOSS_API_KEY"
```

| Flag | Default | Notes |
| - | - | - |
| `--extract-local` | `false` | Local mode: parse manifest files under the path |
| `--settings` | auto-detected | `scanoss.json`. Its `skip` rules apply under the `dependencies` key |
| `--purl` | — | API mode: the component to query |
| `--requirement` | — | API mode: version or range (optional) |
| `--transient` | `false` | API mode: walk transitive dependencies |
| `--depth` | `10` | Transitive walk depth (with `--transient`) |
| `--limit` | `10` | Transitive result limit (with `--transient`) |

`dependencies` also takes the API flags.

## Decoration lookups

Each decoration command queries the SCANOSS v3 API about one or more components. Each one is a
parent command with one subcommand per operation, and running a command with no subcommand uses its
default operation. The input is a list of PURLs, which you give by repeating `--purl` or by passing
`--input`. The CLI splits the list into chunks and queries them concurrently.

All decoration commands share these flags: `--purl` (repeatable), `--requirement` (version or
range), `--input` (a PURL file, either newline-delimited `purl[,requirement]` or JSON
`{"components":[...]}`), `--chunk-size` (10), and `-t, --workers` (5). They also take the API flags.

| Command | Subcommands |
| - | - |
| `vulnerabilities` | `components` (default), `cpes` |
| `cryptography` | `algorithms` (default), `algorithms-range`, `versions-range`, `hints`, `hints-range` |
| `licenses` | `declared` (default), `attribution`, `evidence` |
| `geoprovenance` | `origin` (default), `countries` |
| `copyright` | `evidence` (default), `holders` |
| `components` | `search` (default), `versions`, `releases`, `status` |

```bash theme={null}
scanoss-cli vulnerabilities --purl 'pkg:github/scanoss/engine' --api-key "$SCANOSS_API_KEY"
scanoss-cli cryptography algorithms-range --purl 'pkg:github/scanoss/engine' --requirement '>5.0.0' --api-key "$SCANOSS_API_KEY"
scanoss-cli licenses attribution --purl 'pkg:github/scanoss/engine' --api-key "$SCANOSS_API_KEY"
scanoss-cli geoprovenance countries --purl 'pkg:github/scanoss/engine' --api-key "$SCANOSS_API_KEY"
scanoss-cli copyright holders --purl 'pkg:github/scanoss/engine' --api-key "$SCANOSS_API_KEY"
```

`components search`, `versions` and `releases` take their own flags instead of a PURL list:

```bash theme={null}
# Search by vendor/component/term
scanoss-cli components --vendor scanoss --component engine --limit 20 --api-key "$SCANOSS_API_KEY"

# Known versions (with licences) for a purl
scanoss-cli components versions --purl 'pkg:github/scanoss/engine' --limit 50 --api-key "$SCANOSS_API_KEY"

# Release notes: all, a single version, or a semver range
scanoss-cli components releases --purl 'pkg:github/scanoss/engine' --requirement '>=1.0.0, <=2.0.0' --api-key "$SCANOSS_API_KEY"

# Lifecycle status for a PURL
scanoss-cli components status --purl 'pkg:github/scanoss/engine' --requirement '1.2.3' --api-key "$SCANOSS_API_KEY"

# Free-text search, paginated
scanoss-cli components search --search engine --purl-type github --limit 20 --offset 0 --api-key "$SCANOSS_API_KEY"
```

| Subcommand | Flags |
| - | - |
| `components search` | `--search`, `--vendor`, `--component` (at least one), `--purl-type` (default `github`), `--limit`, `--offset` |
| `components versions` | `--purl`, `--limit` (`0` = server default) |
| `components releases` | `--purl` (required), `--requirement` (exact version or semver range), `--limit`, `--offset`. With no `--requirement`, lists all releases. |
| `components status` | Shared decoration flags (PURL list) |

When a component exists but has no release notes for the resolved version, `components releases`
prints a "no release notes available" notice on stderr, still emits the JSON, and exits `0`.


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