> 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`. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.interlynk.io/lynkctl/faq.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.