> For the complete documentation index, see [llms.txt](https://docs.interlynk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interlynk.io/lynkctl/faq.md).

# FAQ

Practical answers for generating SBOMs with lynkctl. For platform-wide questions, see the main [Frequently Asked Questions](/support/faq.md).

***

## Basics

### What is the simplest command?

```bash
lynkctl generate .
```

This auto-detects the project and writes the SBOM to stdout. Add `-o` to write to a file:

```bash
lynkctl generate . -o sbom.cdx.json
```

### Does lynkctl build my project?

No. For compiled projects, lynkctl reads your build system — build files and, where available, build metadata — to work out what would be compiled and linked, without ever executing the build. For package-manager projects, it reads the manifests and lockfiles directly. No compiler, toolchain, or package manager needs to run.

### Which ecosystems does lynkctl support?

lynkctl has two provider families. **Build providers** cover compiled C/C++ and embedded projects: GNU Make, CMake, and IAR Embedded Workbench for Arm. **Manifest providers** cover package-manager projects: JavaScript/npm (including Yarn, pnpm, Bun), Python, Go, Rust/Cargo, Ruby/RubyGems, PHP/Composer, .NET/NuGet, and Java (Maven and Gradle). See the [Overview](/lynkctl/lynkctl.md#supported-ecosystems) for the full list and the files each provider is detected from.

### How does lynkctl know which provider to use?

It auto-detects from root-level signals — a `Makefile`, a `go.mod`, a `pom.xml`, and so on. If a directory contains signals for more than one ecosystem, detection is ambiguous and lynkctl reports `MULTI_ECOSYSTEM_DETECTED`; pass `--provider` to choose.

### Does lynkctl need the package manager installed?

No. Manifest providers read `package.json`, `go.mod`, `pom.xml`, lockfiles, and similar descriptors directly. The package manager does not run, and no network access is required.

### What output format does lynkctl produce?

CycloneDX 1.6+ and SPDX 3.0+ (Experimental) SBOMs, validated against the official schemas. The SBOM is written to stdout, or to the path given with `--output` (`-o`).

### What command should I use in CI?

```bash
lynkctl generate . --strict -o sbom.cdx.json
```

`--strict` exits non-zero if lynkctl reports warnings; errors always exit non-zero. See [Running in CI/CD](/lynkctl/how-to-guides/ci-cd.md).

### What SBOM should I send to Interlynk support for analysis?

For a compiled C/C++ or embedded project, this is the most useful shape to share:

```bash
lynkctl generate . \
  --reproducible --timestamp 2023-11-14T22:13:20Z \
  --include-source-files --exclude-header-files \
  --evidence \
  -o sbom.cdx.json
```

It produces deterministic output, includes source-file components, drops header-file noise, and records evidence for how every field was determined. Add `-v` for verbose diagnostics on stderr when troubleshooting. For a package-manifest project, drop `--include-source-files --exclude-header-files` — those apply only to C/C++ build providers.

### How do I get lynkctl?

lynkctl is distributed by Interlynk. Contact Interlynk to obtain the binary for your platform. See [Installation](/lynkctl/installation.md).

## Build Systems

### How do I choose the build system?

Use auto-detection unless the project contains more than one build system, or you need to match a specific customer build. Force one with `--provider`:

```bash
lynkctl generate . --provider gnu-make -o sbom.cdx.json
lynkctl generate ./project.ewp --provider iar --iar-config Debug -o sbom.cdx.json
```

If both a `Makefile` and an IAR project are present, pass `--provider` explicitly. See the [GNU Make](/lynkctl/how-to-guides/gnu-make.md), [CMake](/lynkctl/how-to-guides/cmake.md), and [IAR](/lynkctl/how-to-guides/iar.md) guides.

## Source Detail

### How do I include source files as SBOM components?

```bash
lynkctl generate . --include-source-files --exclude-header-files -o sbom.cdx.json
```

`--include-source-files` emits one component per first-party source file; `--exclude-header-files` drops the headers. This is usually the better shape for C and embedded firmware audits. Both flags apply to C/C++ build providers only.

### How do I see how lynkctl decided a name, version, or license?

Pass `--evidence`. lynkctl then emits CycloneDX evidence — identity methods, occurrences, license and copyright evidence, confidence values, and tool references. Use it when the SBOM needs to be reviewed or defended. See [Evidence & Confidence](/lynkctl/evidence.md).

### What does the confidence score on a component mean?

It indicates how strongly a conclusion is supported. Scores of 0.85 and above come from authoritative sources such as explicit declarations and build commands; 0.60 to 0.84 are inferred from build structure or heuristics; below 0.60 are fallback heuristics that warrant review. See [Evidence & Confidence](/lynkctl/evidence.md).

### Why is a component missing a version or license?

lynkctl could not find authoritative information for that field, and reports it with `NO_VERSION_FOUND` or `NO_LICENSE_FOUND`. Run with `-v` to see which components are affected. If you know the correct value, supply it through a `--overrides` file.

### How do I make output stable for diffs?

```bash
lynkctl generate . --reproducible --timestamp 2023-11-14T22:13:20Z -o sbom.cdx.json
```

`--reproducible` sorts collections and makes identifiers deterministic; `--timestamp` sets the embedded timestamp. You can also use the `SOURCE_DATE_EPOCH` environment variable. See [Reproducible SBOMs](/lynkctl/how-to-guides/reproducible.md).

## Third-Party and Vendored Code

### How do I mark a third-party source directory as a component?

Use `--vendored-root`, repeating it for multiple subtrees:

```bash
lynkctl generate . \
  --vendored-root third_party/ringbuf \
  --vendored-root third_party/mbedtls \
  -o sbom.cdx.json
```

Use this when a third-party subtree should be its own component rather than a set of individual source files. `--vendored-root` applies to the GNU Make, CMake, and IAR providers.

### How do I include third-party code that is compiled but not linked?

```bash
lynkctl generate . --include-unlinked-vendored -o sbom.cdx.json
```

This emits vendored code seen during build analysis even when it is not linked into the final binary.

### How do I identify modified or patched OSS copies?

```bash
lynkctl generate . --deep-scan -o sbom.cdx.json
```

`--deep-scan` uses slower fingerprint matching to catch modified copies of open-source code.

{% hint style="warning" %}
`--deep-scan` is a work in progress. Treat results from this path as experimental for now.
{% endhint %}

## Enrichment and Corrections

### How do I run lynkctl in an air-gapped environment?

Pre-fetch the OSS-index database on a connected machine, transfer it, and point lynkctl at the local copy with `--oss-index-db`. See [Air-Gapped Environments](/lynkctl/how-to-guides/air-gapped.md) for the full procedure.

### How do I disable enrichment?

Disable only the OSS-index matching, or every enrichment step:

```bash
lynkctl generate . --no-oss-index -o sbom.cdx.json   # OSS-index only
lynkctl generate . --no-enrich -o sbom.cdx.json      # git, pkg-config, OS packages, OSS-index, overrides
```

Use `--no-enrich` when the SBOM should reflect only build-system extraction.

### lynkctl got a component wrong. How do I correct it?

Use a `--overrides` YAML file. Each entry matches a component by name or by source-file glob and replaces its fields. Overrides resolve at confidence 1.0 and win over auto-detected values; an entry that matches nothing emits `OVERRIDE_NO_MATCH`. See [Generating SBOMs](/lynkctl/generate.md#manual-overrides) for the file format.

## Diagnostics and Output

### Why did my build fail after I added `--strict`?

`--strict` turns any warning-level diagnostic into a non-zero exit. The SBOM is still written; lynkctl exits `1` because warnings were present. Run with `-v` to see the warnings, then resolve them or remove `--strict`. See [Diagnostics & Exit Codes](/lynkctl/diagnostics.md).

### What do the exit codes mean?

`0` is success. `1` is a runtime error, a diagnostic error, or a `--strict` run with warnings. `2` is a usage error such as a bad flag or missing path.

### How do I reduce console output?

`lynkctl generate . -q` suppresses the per-SBOM summary line. Errors still print.

### How do I get more diagnostic detail?

`--verbose` (`-v`) is repeatable:

| Flag   | Detail shown                                    |
| ------ | ----------------------------------------------- |
| `-v`   | Per-diagnostic detail and pipeline debug events |
| `-vv`  | Adds debug and provenance detail                |
| `-vvv` | Adds trace-level timing detail                  |

### Can I pipe the SBOM into another tool?

Yes. The SBOM goes to stdout; all diagnostics, summaries, and progress go to stderr, so piping stdout never mixes in diagnostic noise.

## OSS-Index Database

### Do I need the OSS-index database?

Only for vendored open-source identification. If you do not need it, pass `--no-oss-index` and lynkctl skips that step. Otherwise download it once with `lynkctl db download` (roughly 300 MB).

### How do I keep the database current?

`lynkctl db check` compares the cache against the published manifest without changing anything — exit `0` when current, `1` when stale. A common pattern is `lynkctl db check || lynkctl db download`.