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

# Scanning your project

> Scan flags, file skipping, and BOM rules for scanoss-cli.

## Scanning

```bash theme={null}
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY"
scanoss-cli scan ./src/main.go --api-key "$SCANOSS_API_KEY"
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --output results.json
```

`scan` fingerprints the target, uploads the WFP in blocks to `POST /v3/wfp/scan`, and polls
`GET /v3/wfp/scan/<scan-id>` until the scan completes. It prints the scan id as soon as the upload
finishes, so you can resume an interrupted scan with [`results`](#resuming-a-scan).

### Tuning throughput

```bash theme={null}
scanoss-cli scan ./my-project \
  --api-key "$SCANOSS_API_KEY" \
  --threads 20 \
  --chunk-size 2097152          # 2 MiB upload blocks (default 1 MiB)
```

### Keeping the generated WFP

```bash theme={null}
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --save-wfp project.wfp
```

The CLI writes the copy as the scan generates it, in completion order, and that order varies
between runs.
Use the standalone [`wfp`](/en/latest/cli/scanoss-go/quick-start#generate-fingerprints-only)
command when you need byte-reproducible output to diff or hash.

### Scanning a pre-generated WFP

```bash theme={null}
scanoss-cli scan wfp project.wfp --api-key "$SCANOSS_API_KEY"
```

## Resuming a scan

```bash theme={null}
scanoss-cli results <scan-id> --api-key "$SCANOSS_API_KEY" --output results.json
```

`results` works after a Ctrl+C because the uploaded WFP is resumable. A resumed scan applies the
same rules as a direct one, so `results` accepts `--settings`, `-i`/`-n`, `--ranking-threshold`, `--include`
(`vulns`, `licenses`, `crypto`, `geo`), `-f, --format` and `--poll-interval`, plus the
[API flags](#flags-reference).

## Flags reference

The API flags work on every command that reaches the API: `scan`, `scan wfp`, `results`,
`enrich`, `dependencies`, and the decoration commands.

| Flag | Default | Notes |
| - | - | - |
| `--api-url` | `https://api.scanoss.com` | Default endpoint requires `--api-key` |
| `--api-key` | — | |
| `--proxy` | — | Overrides `HTTP_PROXY`/`HTTPS_PROXY`. See [Configuration](/en/latest/cli/scanoss-go/configuration#proxy-and-custom-ca) |
| `--ca-cert` | — | PEM file added to the system trust pool |
| `--ignore-cert-errors` | `false` | Disables TLS verification (insecure) |
| `-o, --output` | stdout | |

`scan` and `scan wfp` share the scan flags.

| Flag | Default | Notes |
| - | - | - |
| `-f, --format` | `raw` | `raw` / `spdx` / `cyclonedx` |
| `--include` | — | Extra output layers. See [Output layers](#output-layers). `scan wfp` accepts all except `deps` |
| `--settings` | auto-detected `scanoss.json` | |
| `--chunk-size` | `1048576` (1 MiB) | WFP upload block size, bytes |
| `--poll-interval` | `2s` | Scan status poll cadence |
| `-i, --identify <file>`, `-n, --ignore <file>` | — | A component list, CycloneDX, SPDX, or raw result file. See [BOM rules](#bom-rules) |
| `--ranking-threshold` | `-1` (off) | `-1`..`10`; `-1` and `0` both mean off |

The fingerprinting flags work only on `scan <path>` and the standalone
[`wfp`](#fingerprinting-only) command. `scan wfp` receives a WFP that is already assembled, so it
doesn't accept them, and passing `--skip-headers` or `--skip-headers-limit` to it is an error.

| Flag | Default | Notes |
| - | - | - |
| `-t, --threads` | `10` | Fingerprint workers |
| `--save-wfp` | — | Keep the generated WFP alongside the scan (`scan` only) |
| `--min-size` / `--max-size` | `0` / `0` | Bytes. `0` max means unlimited |
| `--gitignore` | `true` | |
| `--all-extensions`, `--all-folders`, `--all-hidden` | `false` | See [Skipping files](#skipping-files) |
| `--skip-headers` | `true` | Drops each file's leading licence header, comments and imports from its fingerprint |
| `--skip-headers-limit` | `0` (no limit) | |

<Warning>
  `--skip-headers` changes the fingerprint. A WFP taken with it off won't match one taken with it
  on, so keep the setting consistent across runs you intend to compare.
</Warning>

## Fingerprinting only

`wfp` generates fingerprints without contacting the API, so it needs no key:

```bash theme={null}
scanoss-cli wfp ./my-project > project.wfp
scanoss-cli wfp ./src/main.go -o main.wfp
scanoss-cli wfp ./my-project --threads 20 --min-size 100
```

It accepts the fingerprinting flags above plus `-o, --output` and `--settings`. Unlike `scan --save-wfp`, its output is byte-reproducible, so use it when you need to diff or hash a WFP.

## Skipping files

Before scanning, the CLI filters out build directories, vendored dependencies, generated and
binary files, model weights (`.safetensors`, `.gguf`, `.onnx`, `.pt`, `.bin`), and oversized files.
There is **no minimum file size by default**. Set one with `--min-size`:

```bash theme={null}
# 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` turns off the built-in *file* rules, which match extensions, name endings, and
exact names. `--all-folders` turns off the *directory* rules. They are separate switches because
someone who wants every folder scanned rarely wants every binary fingerprinted too. `--all-hidden`
includes dotted entries, `.git` among them.

To set skip rules for the whole project, use `scanoss.json`:

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

You can use the flags and `scanoss.json` together. `--min-size` and `--max-size` apply to every
file, while a `skip.sizes` rule applies only to the files its `patterns` match.

## BOM rules

Configure a Bill of Materials in `scanoss.json`. The CLI finds the file in the target
automatically, or you can pass its path with `--settings`:

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

```bash theme={null}
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --settings my-config.json
```

The CLI applies every rule on the client side, after results come back, in this order:

1. **`bom.ignore`** (alias `bom.exclude`) drops the components it names from each file's
   matches.
2. **`bom.identify`** (alias `bom.include`) marks the components it names as `"identified":
   true` and moves them to the front of their file's matches.
3. **`--ranking-threshold`** drops matches whose component ranks worse than the threshold.
4. **`bom.remove`** neutralizes whole files.
5. **`bom.replace`** re-points the survivors at their `replace_with` component.

Details that change results:

* **Scoping.** An entry may be scoped by `purl`, by `path`, or both. Where several entries cover
  the same file, the most specific one wins:

  ```json theme={null}
  { "bom": { "identify": [{ "purl": "pkg:npm/vue@2.6.14", "path": "vendor/vue/" }] } }
  ```

* **Canonical PURLs only.** `bom.ignore` and `bom.identify` match a component's canonical PURL,
  not its aliases. `bom.remove` and `bom.replace` do match aliases.

* **`bom.identify` wins.** It protects its PURLs from every filter in this list: `bom.ignore`,
  `bom.remove`, and the ranking threshold.

* **Ranking threshold.** Rank is how well a component explains a match; lower is stronger, and
  real ranks run from 1 to 9. Matches with no rank, or the engine's `999` "no ranking information"
  sentinel, are never filtered.

* **Where `identified` shows up.** The CLI writes the flag on each matched file's evidence, and on the
  component as a summary, because a `path`-scoped rule claims a component only in the files it
  covers. CycloneDX output carries the component-level flag as a `scanoss:identified` property.
  Only `raw` output has the per-file detail.

`-i, --identify <file>` and `-n, --ignore <file>` on the command line add unscoped entries to the
same rules, and you can combine them with `--settings`. Each takes a file, which can be a SCANOSS
component list (`{"components":[{"purl":"..."}]}`), CycloneDX, SPDX, or this CLI's own `raw`
output. The CLI detects the type from the content.

## Snippet settings in scanoss.json

`scanoss.json` can also carry fingerprinting and filtering settings:

```json theme={null}
{
  "settings": {
    "file_snippet": {
      "skip_headers": true,
      "skip_headers_limit": 50,
      "ranking_threshold": 5
    }
  }
}
```

<Warning>
  These keys **override** the `--skip-headers`, `--skip-headers-limit` and `--ranking-threshold`
  flags. That is the reverse of every other setting in this CLI. SCANOSS-PY behaves the same way,
  so both clients read one settings file identically. If a flag seems to have no effect, check
  for the key in `scanoss.json` and remove it to let the flag win.
</Warning>

`ranking_threshold` accepts values from `-1` to `10`, where `-1` and `0` both mean off. The CLI
clamps out-of-range values and prints a warning. Other `file_snippet` keys, such as
`min_snippet_hits`, `ranking_enabled`, and `honour_file_exts`, tune the matching engine. This CLI
ignores them because it doesn't forward scan settings to the server.

## Output layers

By default a scan reports only the components it detected. `--include` adds extra layers, which
cover both detected and declared components:

| Layer | What it adds |
| - | - |
| `deps` | Declared dependencies parsed from the project's manifests and resolved. Needs a source tree, so `scan wfp` rejects it with an error. |
| `vulns` | Known vulnerabilities. |
| `licenses` | Declared/concluded licences per component. |
| `crypto` | Cryptographic algorithms. |
| `geo` | Contributor geographic provenance. |

```bash theme={null}
scanoss-cli scan ./my-project --api-key "$SCANOSS_API_KEY" --include deps,vulns,licenses
```

If the chosen `--format` can't represent a layer, the CLI doesn't gather that layer and prints a
message up front. `raw` renders every layer, `cyclonedx` drops `crypto` and `geo`, and `spdx` drops
`vulns`, `crypto`, and `geo`.


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