Commands & Arguments

Every command also accepts --help for its exhaustive, always-current flag list: scanoss-cli <command> --help.

Global Flags

Available on every command:

Flag	Description
`-v`, `--verbose`	Enable debug logging to stderr (default: warnings and errors only). Never writes to stdout, so it can’t interfere with `--output` or piped results. Shows the scan flow, each API request (method/URL/status/duration), and fingerprinting.
`--version`	Print the version (single-sourced from the git tag).
`--help`	Help for any command or subcommand.

scanoss-cli --help
scanoss-cli scan --help
scanoss-cli --version

Authentication & Endpoints

The default endpoint is https://api.scanoss.com and requires an API key. A custom endpoint (an on-prem deployment, for example) via --api-url may run keyless.

# Default endpoint: pass a key (a subscription is required)
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY"

# Reference the key from the environment
scanoss-cli vulnerabilities --purl 'pkg:github/scanoss/engine' --api-key "$SCANOSS_API_KEY"

# Custom / on-prem endpoint may run without a key
scanoss-cli scan ./my-project --api-url https://scanoss.internal.example.com

Targeting the default endpoint without --api-key fails fast with a banner, no request is sent. On a 401, the CLI prints an “Unauthorized” hint.

TLS / Certificates

For self-signed or internal endpoints:

# Add a CA to the system pool — verification stays on
scanoss-cli scan ./my-project \
  --api-url https://scanoss.internal.example.com \
  --ca-cert /path/to/internal-ca.pem

# Or skip verification entirely
scanoss-cli scan ./my-project \
  --api-url https://scanoss.internal.example.com \
  --ignore-cert-errors        # INSECURE: disables TLS verification

--proxy overrides HTTP_PROXY/HTTPS_PROXY for one run and honours NO_PROXY. PAC files are not supported. Both flags are available on every command that reaches the API, and can be stored with config set, see Configuration.

wfp

Generate WFP fingerprints without contacting the API.

# Fingerprint a folder (to stdout)
scanoss-cli wfp ./my-project

# Fingerprint a single file, save to a .wfp file
scanoss-cli wfp ./src/main.go > main.wfp

# More workers
scanoss-cli wfp ./my-project --threads 20

# Skip files below 100 bytes
scanoss-cli wfp ./my-project --min-size 100

Flag	Description
`-t`, `--threads`	Fingerprint workers (default `10`).
`-o`, `--output`	Write to a file instead of stdout.
`--settings`	Path to `scanoss.json` (auto-detected by default).
`--gitignore`	Honour `.gitignore` (default `true`).
`--min-size`	Skip files below this many bytes (default `0`).
`--max-size`	Skip files above this many bytes (`0` = unlimited).
`--all-extensions`	Fingerprint every extension, including built-in skip lists.
`--all-folders`	Include every folder, including built-in skip lists.
`--all-hidden`	Include dotfiles and dot-directories (`.git` included).

The size bounds mean the same here as on scan, see Skipping Files.

scan

Fingerprint a folder or file, upload the WFP to the SCANOSS v3 API, and poll until the scan completes.

# Scan a folder
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY"

# Scan a single file
scanoss-cli scan ./src/main.go --api-key "$SCANOSS_API_KEY"

# Save results to a file
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --output results.json

Tune workers and the upload block size. The WFP streams through a temporary file and is uploaded in parallel blocks, so memory stays flat however large the tree; --chunk-size sets the upload block size in bytes.

scanoss-cli scan ./my-project \
  --api-key "$SCANOSS_API_KEY" \
  --threads 20 \
  --chunk-size 2097152          # 2 MiB blocks (default 1 MiB)

Keep the generated WFP alongside the scan. The copy is written while the scan generates it; its entries are in completion order, which varies between runs, use the wfp command when you need byte-reproducible output to diff or hash.

scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --save-wfp project.wfp

Scan a pre-generated WFP file (no fingerprinting):

scanoss-cli scan wfp project.wfp --api-key "$SCANOSS_API_KEY"

How it works. Blocks are POSTed to /v3/wfp/scan as application/octet-stream with a Content-Range header and a shared X-Scan-Id. The CLI then polls GET /v3/wfp/scan/<scan-id>. The scan id is printed as soon as the upload finishes, so an interrupted scan is resumable, see results.

Flag	Description
`--api-url`, `--api-key`	Endpoint and credentials, see Authentication & Endpoints.
`-f`, `--format`	`raw` (default), `spdx`, or `cyclonedx`.
`--include`	Extra output layers, see Output Layers.
`-o`, `--output`	Write to a file instead of stdout.
`--settings`	Path to `scanoss.json` (auto-detected by default).
`--chunk-size`	WFP upload block size in bytes (default `1048576`, 1 MiB).
`--poll-interval`	Scan status poll cadence (default `2s`).
`--proxy`, `--ca-cert`, `--ignore-cert-errors`	See TLS / Certificates.
`-t`, `--threads`	Fingerprint workers (default `10`).
`--save-wfp`	Also write the generated WFP to this path.
`--min-size` / `--max-size`	Same as `wfp`.
`--gitignore`	Honour `.gitignore` (default `true`).
`--all-extensions`, `--all-folders`, `--all-hidden`	Same as `wfp`.

These persistent flags are shared with scan wfp.

Skipping Files

Files are filtered before scanning (build dirs, vendored deps, generated/binary files, oversized files). Toggle the sources with flags, or configure project rules in scanoss.json, see scanoss.json Reference. There is no minimum file size by default. However small a file is, it’s fingerprinted unless another rule skips it. Set a floor with --min-size:

# Skip files below 100 bytes
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --min-size 100

# Keep files between 100 bytes and 1 MiB
scanoss-cli scan ./my-project \
  --api-key "$SCANOSS_API_KEY" \
  --min-size 100 \
  --max-size 1048576

# Fingerprint everything the built-in lists would drop, and ignore .gitignore
scanoss-cli scan ./my-project \
  --api-key "$SCANOSS_API_KEY" \
  --all-extensions \
  --all-folders \
  --gitignore=false

--all-extensions drops the built-in file rules, extensions, name endings, and exact names, and --all-folders the directory ones. They’re separate switches because the two exclude very different amounts: a caller who wants every folder scanned rarely also wants every binary fingerprinted. --all-hidden includes entries whose name begins with a dot, version-control metadata among them: .git is excluded for being hidden, like any other dotted entry, so asking for every hidden entry gets a scan of the repository objects too. The size bounds are independent of all three: they’re what you asked for, not a built-in, so they still apply when the built-in skip lists are off. The two bounds read differently. --min-size is literal: --min-size 0, the default, admits every file, because every file is at least 0 bytes. --max-size can’t work that way, since a literal maximum of 0 would exclude everything, so there 0 means “unlimited”. A negative value, or a --min-size above a non-zero --max-size, is rejected before any file is read. scanoss.json equivalent (per-project skip rules):

{
  "settings": {
    "skip": {
      "patterns": { "scanning": ["dist/**", "**/*.min.js", "docs/"] },
      "sizes":    { "scanning": [{ "patterns": ["*.bin"], "min": 0, "max": 1048576 }] }
    }
  }
}

The two aren’t alternatives, they compose. --min-size/--max-size apply to every file, while a skip.sizes rule applies only to the files its patterns match (a rule with no patterns matches nothing and is ignored). Use the flags for a blanket bound, and skip.sizes when one file type deserves different limits from the rest.

BOM Context

Configure a Bill of Materials in scanoss.json (auto-detected in the target, or pass --settings):

{
  "bom": {
    "include": [{ "purl": "pkg:github/scanoss/engine" }],
    "remove":  [{ "purl": "pkg:github/scanoss/scanoss" }],
    "replace": [{ "purl": "pkg:github/wrong/lib", "replace_with": "pkg:github/right/lib@2.1.0" }]
  }
}

scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY"            # auto-detected
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --settings my-config.json

bom.remove and bom.replace are applied client-side, after results come back, and in that order: matching components are dropped, then the survivors covered by a replace rule are re-pointed at their replace_with component. An entry may be scoped by purl, by path, or by both; where several cover the same file the most specific one wins. bom.include only protects its PURLs from removal and is not yet honored server-side; identify/ignore are not applied.

Output Layers (`--include`)

By default a scan reports only the components it detected. --include opts into extra output layers, gathered over both detected and declared components:

Layer	What It Adds
`deps`	Declared dependencies parsed from the project’s manifests (`package.json`, `go.mod`, …) and resolved. Needs a source tree, so it’s ignored for `scan wfp`.
`vulns`	Known vulnerabilities.
`licenses`	Declared/concluded licenses per component.
`crypto`	Cryptographic algorithms.
`geo`	Contributor geographic provenance.

scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --include deps,vulns,licenses

Gathering follows --include, narrowed to what the chosen --format can render: a layer the format can’t represent is skipped (not gathered) with an up-front Skipping <layer> message. raw renders every layer; cyclonedx drops crypto/geo; spdx drops vulns/crypto/geo.

SBOM Output

scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --format spdx      --output sbom-spdx.json
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --format cyclonedx --output sbom-cdx.json
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --format raw       --output results.json

raw — the neutral inventory (components tagged by scope, per-component layers inline, and a flat vulnerabilities list) wrapped in a versioned envelope. Default.
spdx — SPDX 2.3.
cyclonedx — CycloneDX 1.7 (licenses, evidence, vulnerabilities).

Components that share the same identity (PURL + version) are collapsed into one, so the same package listed in both package.json and package-lock.json, or detected and also declared, is emitted once; different versions of the same PURL are kept. In SPDX, multiple licenses on a component are combined with AND.

results

Retrieve the results of a scan by the id printed during scan (works after a Ctrl+C, the uploaded WFP is resumable):

scanoss-cli results <scan-id> --api-key "$SCANOSS_API_KEY" --output results.json

Polls GET /v3/wfp/scan/<scan-id> until complete.

sbom

Produce an SBOM from a scanoss raw inventory, or convert an existing SBOM between formats, offline. The input format is detected from the file content.

# SPDX -> CycloneDX
scanoss-cli sbom bom.spdx.json --format cyclonedx --output bom.cdx.json

# CycloneDX -> SPDX
scanoss-cli sbom bom.cdx.json --format spdx --output bom.spdx.json

# scanoss raw result -> CycloneDX or SPDX
scanoss-cli sbom results.json --format cyclonedx --output bom.cdx.json

Inputs: a scanoss raw inventory (the scan raw output), CycloneDX, or SPDX (JSON), detected from content. Target (-f, --format): cyclonedx or spdx. Conversion is best-effort: data the target can’t represent is dropped, for example SPDX 2.3 has no vulnerability model, so vulnerabilities are omitted (with a warning) when converting to spdx.

Flag	Description
`-f`, `--format`	`cyclonedx` or `spdx`.
`-o`, `--output`	Write to a file instead of stdout.

enrich

Decorate an existing inventory or SBOM with purl-keyed layers through the SCANOSS API, no source tree, no fingerprinting, no re-scan. Because it’s keyed purely by PURL, it’s re-runnable (weekly, for example) to refresh the layers against the same file.

# 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

Inputs: a scanoss raw inventory (the scan raw output), CycloneDX, or SPDX (JSON), detected from the file content. Layers (--include): the purl-keyed layers vulns, licenses, crypto, geo.

deps is not an enrich layer, dependency analysis needs a manifest/source tree and can’t be derived from a components list, so --include deps errors on enrich.

The output format defaults to the input’s (raw→raw, cyclonedx→cyclonedx, spdx→spdx); use -f, --format to convert in the same pass. A layer the output format can’t represent is skipped up front with a notice (spdx skips vulns/crypto/geo, cyclonedx skips crypto/geo), the same capability rules as scan. Enrichment is non-fatal: a failed service is logged and skipped, and a partial result is still written.

Flag	Description
`--include`	`vulns`, `licenses`, `crypto`, `geo` (repeatable).
`-f`, `--format`	`raw`, `spdx`, or `cyclonedx`.
`-o`, `--output`	Write to a file instead of stdout.
`--api-url`, `--api-key`, `--ignore-cert-errors`	Auth flags, see Authentication & Endpoints.

dependencies

Two modes. Local mode — parse manifest files under a path and query the API:

scanoss-cli dependencies ./my-project --extract-local --output deps.json

API mode — query a component’s dependencies (--requirement is optional):

# Direct dependencies
scanoss-cli dependencies --purl 'pkg:github/scanoss/engine' --requirement '5.4.7' \
  --api-key "$SCANOSS_API_KEY"

# 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	Description
`--extract-local`	Parse manifests under a local path instead of querying the API.
`--purl`	Component PURL to query.
`--requirement`	Version or range (optional).
`--transient`	Query transitive rather than direct dependencies.
`--depth`	Transitive traversal depth (default `10`).
`--limit`	Result limit (default `10`).
`-o`, `--output`	Write to a file instead of stdout.

Endpoints: direct → POST /v3/dependencies/dependencies; transitive → POST /v3/dependencies/transitive.

Decoration Commands

Query the SCANOSS v3 API about components. Each command below is a parent with one subcommand per operation; running it bare uses the default operation. Input is a list of PURLs (repeat --purl, or pass --input), split into chunks and queried concurrently. Shared flags:

Flag	Description
`--purl`	Component PURL (repeatable).
`--requirement`	Default version/range.
`--input`	PURL file, see format below.
`--chunk-size`	PURLs per request (default `10`).
`-t`, `--workers`	Max concurrent requests (default `5`).
`--api-url`, `--api-key`, `--ignore-cert-errors`	Auth flags.
`-o`, `--output`	Write to a file instead of stdout.

The --input file is either newline-delimited purl[,requirement], or JSON {"components":[{"purl":"...","requirement":"..."}]}.

`vulnerabilities` — `components` (default), `cpes`

scanoss-cli vulnerabilities --purl 'pkg:github/scanoss/engine' --api-key "$SCANOSS_API_KEY"
scanoss-cli vulnerabilities cpes --purl 'pkg:github/scanoss/engine' --api-key "$SCANOSS_API_KEY"

`cryptography` — `algorithms` (default), `algorithms-range`, `versions-range`, `hints`, `hints-range`

The version or range goes in --requirement.

scanoss-cli cryptography --purl 'pkg:github/scanoss/engine' --requirement '5.0.1' --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 cryptography hints-range --purl 'pkg:github/scanoss/engine' --requirement '>5.0.0' --api-key "$SCANOSS_API_KEY"

`licenses` — `declared` (default), `attribution`, `evidence`

scanoss-cli licenses --purl 'pkg:github/scanoss/engine' --api-key "$SCANOSS_API_KEY"             # declared
scanoss-cli licenses attribution --purl 'pkg:github/scanoss/engine' --api-key "$SCANOSS_API_KEY"
scanoss-cli licenses evidence --purl 'pkg:github/scanoss/engine' --api-key "$SCANOSS_API_KEY"

`geoprovenance` — `origin` (default), `countries`

scanoss-cli geoprovenance --purl 'pkg:github/scanoss/engine' --requirement '5.4.7' --api-key "$SCANOSS_API_KEY"
scanoss-cli geoprovenance countries --purl 'pkg:github/scanoss/engine' --api-key "$SCANOSS_API_KEY"

`copyright` — `evidence` (default), `holders`

scanoss-cli copyright --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` (default), `versions`, `releases`, `status`

search, versions, and releases take their own flags instead of the PURL list.

# Search by vendor/component/term
scanoss-cli components --vendor scanoss --component engine --limit 20 --api-key "$SCANOSS_API_KEY"
scanoss-cli components search --search engine --purl-type github --limit 20 --offset 0 --api-key "$SCANOSS_API_KEY"

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

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

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

Subcommand	Flags
`search`	`--search`, `--vendor`, `--component` (at least one of the three), `--purl-type` (default `github`), `--limit`, `--offset`.
`versions`	`--purl`, `--limit`.
`releases`	`--purl` (required), `--requirement` (an exact version or a semver range), `--limit`, `--offset`. With no `--requirement` it lists all releases; the flags are not mutually exclusive.

When a component exists but has no release notes for the resolved version, the API returns RELEASE_NOTES_UNAVAILABLE, the command prints a “no release notes available” notice on stderr, still emits the JSON, and exits 0 (not an error).

scanoss.json Reference

scanoss.json (or settings.json) carries the BOM context and file-skip rules referenced throughout this page. For the full schema, see Declaring Components.

Default Values

Setting	Default	Notes
`--api-url`	`https://api.scanoss.com`	Default endpoint requires `--api-key`.
`--threads` (scan/wfp)	`10`	Fingerprint workers.
`--format`	`raw`	`raw` / `spdx` / `cyclonedx`.
`--chunk-size` (scan)	`1048576`	WFP upload block size (bytes).
`--poll-interval` (scan)	`2s`	Scan status poll cadence.
`--min-size` / `--max-size`	`0` / `0`	Literal minimum; `0` max means unlimited.
`--chunk-size` (decoration)	`10`	PURLs per request.
`--workers` (decoration)	`5`	Max concurrent requests.
`--depth` / `--limit` (deps)	`10` / `10`	Transitive only.

Documentation

Links

Global Flags

Authentication & Endpoints

TLS / Certificates

wfp

scan

Skipping Files

BOM Context

Output Layers (`--include`)

SBOM Output

results

sbom

enrich

dependencies

Decoration Commands

`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`

scanoss.json Reference

Default Values

​Global Flags

​Authentication & Endpoints

​TLS / Certificates

​wfp

​scan

​Skipping Files

​BOM Context

​Output Layers (--include)

​SBOM Output

​results

​sbom

​enrich

​dependencies

​Decoration Commands

​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

​scanoss.json Reference

​Default Values

Global Flags

Authentication & Endpoints

TLS / Certificates

wfp

scan

Skipping Files

BOM Context

Output Layers (`--include`)

SBOM Output

results

sbom

enrich

dependencies

Decoration Commands

`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`

scanoss.json Reference

Default Values