### Example Usage of Verify Commands

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Demonstrates how to instantiate and use the VerifyAll and VerifyFile commands with their respective options.

```csharp
var allOptions = new VerifyAllCommandOptions
{
    BomFile = "sbom.xml",
    KeyFile = "public.key"
};
var result = await VerifyAllCommand.VerifyAll(allOptions);

var fileOptions = new VerifyFileCommandOptions
{
    File = "sbom.json",
    KeyFile = "public.key",
    SignatureFile = "sbom.json.sig"
};
var result2 = await VerifyFileCommand.VerifyFile(fileOptions);
```

--------------------------------

### Example: Input File Not Found

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

Demonstrates an IOError (exit code 2) when a specified input file is missing.

```bash
$ cyclonedx-cli add files --input-file missing.xml
Error reading input, you must specify a value for --input-file or pipe in content
# Exit code: 2
```

--------------------------------

### Validate BOM and Fail on Errors Example

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/README.md

This example demonstrates how to validate a BOM and configure the CLI to exit with a non-zero status code if validation errors are found. This is useful for build automation.

```bash
cycldx-cli validate --input-file sbom.xml --fail-on-errors
```

--------------------------------

### Sign SBOM Command

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Example of signing an SBOM file using a private key. The '--key-file' option specifies the path to the private key.

```bash
cyclonedx-cli sign bom sbom.xml --key-file private.key
```

--------------------------------

### Pipeline-Based Workflow for SBOM Processing

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/INDEX.md

Demonstrates a pipeline workflow using standard input/output. This example converts an XML SBOM to JSON, then analyzes it for multiple component versions.

```bash
cat sbom-old.xml | \
    cyclonedx-cli convert --input-format xml --output-format json | \
    cyclonedx-cli analyze --input-format json --multiple-component-versions
```

--------------------------------

### Merge Command Options Example

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Demonstrates how to configure and execute the merge command with hierarchical merging enabled. Ensure input files and necessary parameters like Name and Version are provided for hierarchical merges.

```csharp
var options = new MergeCommandOptions
{
    InputFiles = new List<string> { "bom1.xml", "bom2.xml" },
    OutputFile = "merged.xml",
    InputFormat = CycloneDXBomFormat.xml,
    OutputFormat = CycloneDXBomFormat.xml,
    Hierarchical = true,
    Name = "MyApp",
    Version = "1.0.0"
};
var result = await MergeCommand.Merge(options);
```

--------------------------------

### Validate Command Options Example

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Shows how to set up options for the validate command to check an SBOM file against a specific schema version and fail on errors. The InputFile can be null to read from stdin.

```csharp
var options = new ValidateCommandOptions
{
    InputFile = "sbom.xml",
    InputFormat = ValidationBomFormat.xml,
    InputVersion = SpecificationVersion.v1_4,
    FailOnErrors = true
};
var result = await ValidateCommand.Validate(options);
```

--------------------------------

### Install CycloneDX CLI using Homebrew

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/README.md

This command installs the CycloneDX CLI tool on Linux and macOS systems using the official Homebrew tap. Ensure Homebrew is installed before running this command.

```shell
brew install cyclonedx/cyclonedx/cyclonedx-cli
```

--------------------------------

### Example: Parameter Validation Error - Unsupported Signing Format

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

Shows a ParameterValidationError (exit code 4) when attempting to sign a non-XML BOM.

```bash
$ cyclonedx-cli sign bom sbom.json --key-file private.key
Only XML BOMs are currently supported for signing.
# Exit code: 4
```

--------------------------------

### Format Auto-Detection Example

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Illustrates how the CycloneDX CLI infers input and output formats from file extensions when --input-format or --output-format is set to 'autodetect'.

```bash
cat bom.json | cyclonedx convert --input-format json --output-format xml > bom.xml
```

--------------------------------

### AnalyzeResult JSON Example

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

An example of how the AnalyzeResult is serialized to JSON, showing multiple versions of a component.

```json
{
  "multipleComponentVersions": {
    "log4j-core": [
      {"name": "log4j-core", "version": "2.11.0"},
      {"name": "log4j-core", "version": "2.14.0"}
    ]
  }
}
```

--------------------------------

### Using gron to Search Component Names and Versions in XML BOM

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/README.md

This example shows how to convert an XML BOM to JSON, then use 'gron' and 'grep' to extract component names and versions. This approach is useful for analyzing XML BOMs with gron's JSON-focused capabilities.

```bash
$ cyclonedx convert --input-file bom.xml --output-format json | gron | grep -E "(components\[[[:digit:]]*\].name)|(components\[[[:digit:]]*\].version)"

json.components[0].name = "tomcat-catalina";
json.components[0].version = "9.0.14";
json.components[1].name = "mylibrary";
json.components[1].version = "1.0.0";
```

--------------------------------

### Example: Signature Verification Failure

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

Shows an example of a signature verification failure (exit code 3) when verifying signatures on a BOM.

```bash
$ cyclonedx-cli verify all sbom.xml --key-file public.key
Loading public key...
Loading XML BOM...
Reading signatures...
Found 1 signatures...
Verifying signature 1... failed verification

Signatures failed verification
# Exit code: 3
```

--------------------------------

### Using gron to Search Component Names and Versions in JSON BOM

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/README.md

This example demonstrates how to use 'gron' to transform a JSON BOM into discrete assignments, making it easier to grep for specific fields like component names and versions. It pipes the output of 'gron' to 'grep'.

```bash
$ gron bom-1.2.json | grep -E "(components\[[[:digit:]]*\].name)|(components\[[[:digit:]]*\].version)"

json.components[0].name = "tomcat-catalina";
json.components[0].version = "9.0.14";
json.components[1].name = "mylibrary";
json.components[1].version = "1.0.0";
```

--------------------------------

### Convert XML to JSON and Pipe Output

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/README.md

This example shows how to convert an XML BOM to JSON and pipe the output to another command for further processing, such as filtering with grep.

```bash
cyclonedx-cli convert --input-file sbom.xml --output-format json | grep "somthing"
```

--------------------------------

### Analyze BOM - JSON Output

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Example of JSON output format for BOM analysis, specifically detailing components with multiple versions.

```json
{
  "multipleComponentVersions": {
    "component-name": [
      {"name": "...", "version": "v1"},
      {"name": "...", "version": "v2"}
    ]
  }
}
```

--------------------------------

### Add Files to SBOM Command

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Example of adding files to an SBOM. The '--no-input' flag indicates that no existing SBOM is being read, and '--base-path' specifies the directory to scan for files.

```bash
cyclonedx-cli add files --no-input --base-path ./bin --output-file sbom.json
```

--------------------------------

### Example: Parameter Validation Error - Hierarchical Merge

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

Demonstrates a ParameterValidationError (exit code 4) during a hierarchical merge when name or version is missing.

```bash
$ cyclonedx-cli merge --input-files a.xml b.xml --hierarchical
Name and version must be specified when performing a hierarchical merge.
# Exit code: 4
```

--------------------------------

### Example: Parameter Validation Error - Output Format

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

Illustrates a ParameterValidationError (exit code 4) when the output format is not specified for stdout redirection.

```bash
$ cat bom.json | cyclonedx-cli convert --output-format xml > output.xml
You must specify a value for --output-format when standard output is used
# Exit code: 4
```

--------------------------------

### Analyze BOM - Text Output

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Example of text output format for BOM analysis, including BOM metadata and component version information.

```text
Analysis results for [component]@[version]:
BOM Serial Number: [serial]
BOM Version: [version]
Timestamp: [timestamp]

Components with multiple versions:

[component-name] versions: [v1] [v2] ...
```

--------------------------------

### Convert BOM File

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Example of converting an SBOM from XML to JSON format, specifying input and output files and versions. Use this to transform SBOMs between different formats and versions.

```csharp
var options = new ConvertCommandOptions
{
    InputFile = "sbom.xml",
    InputFormat = ConvertFormat.xml,
    OutputFile = "sbom.json",
    OutputFormat = ConvertFormat.json,
    OutputVersion = SpecificationVersion.v1_4
};
var result = await ConvertCommand.Convert(options);
```

--------------------------------

### Ant Style Include/Exclude Patterns

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/configuration.md

Examples of Apache Ant style patterns used for file inclusion and exclusion in the 'add files' command. These patterns define which files are processed recursively.

```bash
**/**          Match all files recursively
*.txt          Match .txt files in current directory
src/**/*.java  Match Java files in src/ recursively
.git/**        Match everything under .git/ directory
node_modules/**   Match everything under node_modules/
```

--------------------------------

### Sign and Verify SBOM

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/INDEX.md

This snippet shows how to generate keys, sign an SBOM, and then verify its signature. Ensure keys are generated before signing.

```bash
# Generate keys
cyclonedx-cli keygen

# Sign BOM
cyclonedx-cli sign bom sbom.xml

# Verify signature
cyclonedx-cli verify all sbom.xml
```

--------------------------------

### Global Command-Line Options

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/configuration.md

These options are automatically provided by System.CommandLine for help and version information.

```bash
--version         Show version information
-?, -h, --help    Show help and usage information
```

--------------------------------

### Pipeline Processing with Convert

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Illustrates using the CLI in a pipeline, piping JSON SBOM data to the 'convert' command to output XML. Input and output formats must be explicitly specified when using stdin/stdout.

```bash
cat sbom.json | cyclonedx-cli convert --input-format json --output-format xml > sbom.xml
```

--------------------------------

### Verify SBOM Signature Command

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Demonstrates how to verify the signature of an SBOM file using a public key. The '--key-file' option specifies the path to the public key.

```bash
cyclonedx-cli verify all sbom.xml --key-file public.key
```

--------------------------------

### Module Organization

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Illustrates the directory structure of the CycloneDX CLI project, highlighting key files and their purposes within the 'src/cyclonedx/' namespace.

```tree
src/cyclonedx/
├── Program.cs                   Entry point, command registration
├── CliUtils.cs                  I/O and format utilities
├── ExitCode.cs                  Exit code enumeration
├── Commands/                    Command implementations
│   ├── *Command.cs              Command classes
│   ├── *CommandOptions.cs       Options classes
│   └── */                       Subcommand implementations
├── Models/                      Result types
└── Serialization/               CSV support
```

--------------------------------

### Specify Output Path for Key Generation

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

When encountering permission denied errors during key generation, specify a writable directory or a full path for the output key files.

```bash
cyclonedx-cli keygen --private-key-file /tmp/private.key --public-key-file /tmp/public.key
```

--------------------------------

### Main Method Signature

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/utilities.md

The Main method serves as the entry point for the CycloneDX CLI application. It accepts command-line arguments and returns an integer exit code.

```csharp
public static async Task<int> Main(string[] args)
```

--------------------------------

### SignFileCommandOptions C# Class

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Defines the options for signing an arbitrary file, including the file path, key file, and signature file. Use this to configure the signing of any file.

```csharp
internal class SignFileCommandOptions
{
    public string File { get; set; }
    public string KeyFile { get; set; }
    public string SignatureFile { get; set; }
}
```

--------------------------------

### Sign File Command Usage

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/README.md

This snippet shows the usage of the 'sign file' subcommand for creating PKCS1 RSA SHA256 signature files for arbitrary files. It details the required file argument and optional key and signature file parameters.

```bash
file
  Sign arbitrary files and generate a PKCS1 RSA SHA256 signature file

Usage:
  cyclonedx sign file <file> [options]

Arguments:
  <file>  Filename of the file the signature will be created for

Options:
  --key-file <key-file>              Signing key filename (RSA private key in PEM format, defaults to "private.key")
  --signature-file <signature-file>  Filename of the generated signature file (defaults to the filename with ".sig" appended)
```

--------------------------------

### Convert BOM from JSON to XML via Stdin/Stdout

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/README.md

Demonstrates how to pipe a JSON BOM to the CLI for conversion to XML, utilizing stdin for input and stdout for output.

```bash
cat bom.json | cyclonedx-cli convert --input-format json --output-format xml > bom.xml
```

--------------------------------

### VerifyAllCommandOptions C# Class

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Specifies the options for verifying all signatures in a BOM file, including the BOM file path and the public key file. Use this to configure the verification of a BOM's signatures.

```csharp
internal class VerifyAllCommandOptions
{
    public string BomFile { get; set; }
    public string KeyFile { get; set; }
}
```

--------------------------------

### SignFileCommand

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Generates a PKCS#1 RSA SHA256 signature for arbitrary files.

```APIDOC
## SignFileCommand

### Purpose
Sign arbitrary files with an RSA private key.

### Entry Point
**Configuration Method**: `SignCommand.Configure(RootCommand rootCommand)`

### Sign File Subcommand

### Description
Generates a PKCS#1 RSA SHA256 signature for arbitrary files.

### Method
`public static async Task<int> SignFile(SignFileCommandOptions options)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **File** (string) - Required - Path to file to sign
- **KeyFile** (string) - Optional - Path to RSA private key in PEM format (defaults to "private.key")
- **SignatureFile** (string) - Optional - Path to write signature (defaults to [file].sig)

### Request Example
```csharp
var fileOptions = new SignFileCommandOptions
{
    File = "sbom.json",
    KeyFile = "private.key",
    SignatureFile = "sbom.json.sig"
};
var result2 = await SignFileCommand.SignFile(fileOptions);
```

### Response
#### Success Response (0)
Exit code 0 indicates success.

#### Response Example
```
Loading private key...
Generating signature...
Writing signature file...
Finished
```
```

--------------------------------

### Input BOM Helper Logic

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Describes the steps involved in the InputBomHelper function, which handles opening, deserializing, and returning a BOM from various input sources.

```plaintext
InputBomHelper() {
  1. Auto-detect format if needed
  2. Open file or stdin
  3. Delegate to appropriate deserializer
  4. Return Bom or null
}
```

--------------------------------

### Add Build Output Files to Existing BOM

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/README.md

Adds build output files from the 'bin' directory to an existing BOM file, specifying input and output formats.

```bash
cyclonedx-cli add files --input-file bom.json --output-format json --base-path bin
```

--------------------------------

### AnalyzeCommandOptions Class

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Defines the options for the 'analyze' command. Use this to specify the input BOM file, its format, the desired output format, and whether to report components with multiple versions.

```csharp
internal class AnalyzeCommandOptions
{
    public string InputFile { get; set; }
    public CycloneDXBomFormat InputFormat { get; set; }
    public CommandOutputFormat OutputFormat { get; set; }
    public bool MultipleComponentVersions { get; set; }
}
```

--------------------------------

### Load BOM from File or Stdin

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/utilities.md

Use InputBomHelper to load a BOM from a specified file or standard input. It supports various formats including CSV, SPDX JSON, and auto-detection.

```csharp
public static async Task<Bom>
    InputBomHelper(
        string filename,
        ConvertFormat format)
```

```csharp
// Load CSV BOM
var bom = await CliUtils.InputBomHelper("sbom.csv", ConvertFormat.csv);

// Load SPDX JSON
var bom2 = await CliUtils.InputBomHelper("sbom.spdx.json", ConvertFormat.spdxjson);

// Load from stdin, auto-detect format
var bom3 = await CliUtils.InputBomHelper(null, ConvertFormat.autodetect);
```

--------------------------------

### Diff BOM Files (Text Output)

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Compares two SBOM files and displays the differences in a human-readable text format. This is useful for tracking changes between SBOM versions.

```csharp
var options = new DiffCommandOptions
{
    FromFile = "sbom-v1.xml",
    ToFile = "sbom-v2.xml",
    FromFormat = CycloneDXBomFormat.xml,
    ToFormat = CycloneDXBomFormat.xml,
    OutputFormat = CommandOutputFormat.text,
    ComponentVersions = true
};
var result = await DiffCommand.Diff(options);
```

--------------------------------

### Generate Signing Key

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Command to generate a new private and public key pair for signing SBOMs. This should be run before signing.

```bash
cyclonedx-cli keygen
```

--------------------------------

### CliUtils.InputBomHelper (CycloneDXBomFormat Overload)

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/utilities.md

Loads a BOM from a specified file or standard input, automatically detecting the format if specified. Handles validation, format detection, stream handling, and deserialization for XML, JSON, and Protobuf formats.

```APIDOC
## InputBomHelper (CycloneDXBomFormat Overload)

### Description
Loads BOM from file or stdin with format detection.

### Method
`public static async Task<Bom> InputBomHelper(
    string filename,
    CycloneDXBomFormat format)
`

### Parameters
#### Path Parameters
- **filename** (string) - Required - File path or null for stdin
- **format** (CycloneDXBomFormat) - Required - Format specification (autodetect, xml, json, protobuf)

### Return Type
`Task<Bom>`

### Behavior
1. **Validation Phase**:
   - If `filename` is null and `format` is autodetect:
     - Writes error to stderr: "Unable to auto-detect input stream format, please specify a value for --input-format"
     - Returns null

2. **Format Detection**:
   - If `format` is autodetect and filename is not null:
     - Calls `AutoDetectBomFormat(filename)`
     - If result is still autodetect, writes error to stderr and returns null

3. **Input Stream**:
   - Opens file for reading if filename provided, otherwise opens standard input
   - Ensures stream is properly disposed

4. **Deserialization**:
   - XML format: `Xml.Serializer.Deserialize(inputStream)`
   - JSON format: `Json.Serializer.DeserializeAsync(inputStream)`
   - Protobuf format: `Protobuf.Serializer.Deserialize(inputStream)`

### Return Value
- `Bom` - Successfully deserialized BOM
- `null` - Format error or format is unrecognized

### Error Cases
- Null return with stderr message if format cannot be determined
- Null return if format value is not recognized

### Example
```csharp
// Load from file with auto-detection
var bom = await CliUtils.InputBomHelper("sbom.xml", CycloneDXBomFormat.autodetect);

// Load from stdin with explicit format
var bom2 = await CliUtils.InputBomHelper(null, CycloneDXBomFormat.json);

// Load from file with explicit format
var bom3 = await CliUtils.InputBomHelper("sbom.json", CycloneDXBomFormat.json);
```
```

--------------------------------

### Diff Command Output - Text Format

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Illustrates the text-based output format for the Diff command, showing added, removed, and unchanged component versions.

```text
Component versions that have changed:

- [group] [name] @ [version]    (removed)
= [group] [name] @ [version]    (unchanged)
+ [group] [name] @ [version]    (added)
```

--------------------------------

### SignBomCommandOptions C# Class

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Specifies the options for signing a BOM file, including the BOM file path and the key file. Use this to configure the signing process for a specific BOM.

```csharp
internal class SignBomCommandOptions
{
    public string BomFile { get; set; }
    public string KeyFile { get; set; }
}
```

--------------------------------

### InputBomHelper Overload for CycloneDXBomFormat

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Loads a BOM from a file or stdin, auto-detecting the format if necessary, using a specified CycloneDXBomFormat.

```csharp
public static async Task<Bom> InputBomHelper(string filename, CycloneDXBomFormat format)
```

--------------------------------

### ConvertCommandOptions Class

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Defines the options for the 'convert' command. Use this to specify input/output files, input/output formats, and the target BOM specification version.

```csharp
internal class ConvertCommandOptions
{
    public string InputFile { get; set; }
    public string OutputFile { get; set; }
    public ConvertFormat InputFormat { get; set; }
    public ConvertFormat OutputFormat { get; set; }
    public SpecificationVersion? OutputVersion { get; set; }
}
```

--------------------------------

### AddFilesCommandOptions Class

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Defines the options for the 'add files' subcommand. Use this to specify input/output files, formats, and inclusion/exclusion patterns for scanning.

```csharp
internal class AddFilesCommandOptions
{
    public string InputFile { get; set; }
    public bool NoInput { get; set; }
    public string OutputFile { get; set; }
    public CycloneDXBomFormat InputFormat { get; set; }
    public CycloneDXBomFormat OutputFormat { get; set; }
    public string BasePath { get; set; }
    public IList<string> Include { get; set; }
    public IList<string> Exclude { get; set; }
}
```

--------------------------------

### Output BOM Helper Logic

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Outlines the process for the OutputBomHelper function, responsible for setting the specification version, opening output streams, and serializing BOM data.

```plaintext
OutputBomHelper() {
  1. Auto-detect format if needed
  2. Set specification version
  3. Open file or stdout
  4. Delegate to appropriate serializer
  5. Return exit code
}
```

--------------------------------

### CycloneDX CLI Project Structure

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/INDEX.md

Overview of the directory structure and key files within the CycloneDX CLI project. This helps in understanding the organization of code related to commands, models, and serialization.

```tree
src/cyclonedx/\
├── Program.cs                    Entry point
├── CliUtils.cs                   I/O and format utilities
├── ExitCode.cs                   Exit code enumeration
├── AssemblyInfo.cs              Assembly metadata
├── Commands/
│   ├── AddCommand.cs            Add command configuration
│   ├── AnalyzeCommand.cs        Analyze command implementation
│   ├── ConvertCommand.cs        Convert command implementation
│   ├── DiffCommand.cs           Diff command implementation
│   ├── MergeCommand.cs          Merge command implementation
│   ├── ValidateCommand.cs       Validate command implementation
│   ├── KeyGenCommand.cs         Key generation implementation
│   ├── SignCommand.cs           Sign command configuration
│   ├── VerifyCommand.cs         Verify command configuration
│   ├── Add/
│   │   ├── AddFilesCommand.cs   Add files implementation
│   │   └── AddFilesCommandOption.cs
│   ├── Sign/
│   │   ├── SignBomCommand.cs    Sign BOM implementation
│   │   ├── SignFileCommand.cs   Sign file implementation
│   │   ├── SignBomCommandOption.cs
│   │   └── SignFileCommandOption.cs
│   ├── Verify/
│   │   ├── VerifyAllCommand.cs  Verify all implementation
│   │   ├── VerifyFileCommand.cs Verify file implementation
│   │   ├── VerifyAllCommandOption.cs
│   │   └── VerifyFileCommandOption.cs
│   ├── CycloneDXBomFormat.cs     Format enum
│   ├── ConvertFormat.cs          Extended format enum
│   ├── CommandOutputFormat.cs    Output format enum
│   ├── ValidationBomFormat.cs    Validation format enum
│   ├── [Command]CommandOptions.cs Option classes
│   └── [Command]Options.cs       Option classes
├── Models/
│   ├── AnalyzeResult.cs          Analyze result type
│   └── DiffResult.cs             Diff result type
└── Serialization/
    └── CsvSerializer.cs          CSV format support
```

--------------------------------

### Analyze BOM for Multiple Component Versions

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/README.md

Analyzes an SBOM in XML format to report components that appear with multiple different versions.

```bash
cyclonedx-cli analyze --input-file sbom.xml --multiple-component-versions
```

--------------------------------

### Validate SBOM Command

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Demonstrates how to validate an SBOM file using the 'validate' command. The '--fail-on-errors' flag can be used to ensure the command exits with a non-zero status code if validation fails.

```bash
cyclonedx-cli validate --input-file sbom.xml --fail-on-errors
```

--------------------------------

### InputBomHelper Overload for ConvertFormat

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Loads a BOM from a file or stdin, auto-detecting the format if necessary, using a specified ConvertFormat.

```csharp
public static async Task<Bom> InputBomHelper(string filename, ConvertFormat format)
```

--------------------------------

### Specify Output Format for Unknown File Extension

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

When the output file has an unknown extension, explicitly set the output format using `--output-format`.

```bash
# Wrong: unknown extension
cyclonedx-cli convert --input-file a.xml --output-file output.dat

# Correct: specifies format
cyclonedx-cli convert --input-file a.xml --output-file output.json --output-format json
```

--------------------------------

### VerifyFileCommandOptions Class

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Defines the options available for the verify file subcommand in the CycloneDX CLI.

```csharp
internal class VerifyFileCommandOptions
{
    public string File { get; set; }
    public string KeyFile { get; set; }
    public string SignatureFile { get; set; }
}
```

--------------------------------

### DiffCommandOptions Class

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Defines the options for the 'diff' command. Use this to specify the two BOM files to compare, their formats, the output format, and whether to report component version changes.

```csharp
internal class DiffCommandOptions
{
    public string FromFile { get; set; }
    public string ToFile { get; set; }
    public CycloneDXBomFormat FromFormat { get; set; }
    public CycloneDXBomFormat ToFormat { get; set; }
    public CommandOutputFormat OutputFormat { get; set; }
    public bool ComponentVersions { get; set; }
}
```

--------------------------------

### Analyze BOM for Multiple Component Versions

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Configures options for analyzing a BOM to identify components with multiple versions. Outputs results in JSON format. Use when you need to detect version discrepancies in your BOM.

```csharp
var options = new AnalyzeCommandOptions
{
    InputFile = "sbom.xml",
    InputFormat = CycloneDXBomFormat.xml,
    OutputFormat = CommandOutputFormat.json,
    MultipleComponentVersions = true
};
var result = await AnalyzeCommand.Analyze(options);
```

--------------------------------

### Input BOM Helper for Loading BOM Data

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/utilities.md

Loads a CycloneDX BOM from a file or standard input, with support for format detection. Handles validation, format detection (including auto-detect), and deserialization for XML, JSON, and Protobuf formats. Returns null on format errors.

```csharp
public static async Task<Bom> InputBomHelper(
    string filename,
    CycloneDXBomFormat format)
```

```csharp
// Load from file with auto-detection
var bom = await CliUtils.InputBomHelper("sbom.xml", CycloneDXBomFormat.autodetect);

// Load from stdin with explicit format
var bom2 = await CliUtils.InputBomHelper(null, CycloneDXBomFormat.json);

// Load from file with explicit format
var bom3 = await CliUtils.InputBomHelper("sbom.json", CycloneDXBomFormat.json);
```

--------------------------------

### KeyGenCommandOptions C# Class

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Defines the options for the keygen command, specifying the output filenames for private and public keys. Use this to configure where generated keys are saved.

```csharp
internal class KeyGenCommandOptions
{
    public string PrivateKeyFile { get; set; }
    public string PublicKeyFile { get; set; }
}
```

--------------------------------

### Sign Arbitrary File

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Generates a PKCS#1 RSA SHA256 signature for an arbitrary file. The signature is saved in binary format to a specified file, defaulting to '[file].sig'.

```csharp
var fileOptions = new SignFileCommandOptions
{
    File = "sbom.json",
    KeyFile = "private.key",
    SignatureFile = "sbom.json.sig"
};
var result2 = await SignFileCommand.SignFile(fileOptions);
```

--------------------------------

### OutputBomHelper Overload for CycloneDXBomFormat

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Writes a BOM to a file or stdout using the specified CycloneDXBomFormat.

```csharp
public static async Task<int> OutputBomHelper(Bom bom, CycloneDXBomFormat format, string filename)
```

--------------------------------

### Convert to XML Before Signing

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

The `sign bom` command currently only supports XML BOMs. Convert JSON or other formats to XML first.

```bash
cyclonedx-cli convert --input-file sbom.json --output-file sbom.xml
cyclonedx-cli sign bom sbom.xml --key-file private.key
```

--------------------------------

### Specify Input Format for Unknown File Extension

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

If an input file has an unknown or missing extension, specify the format using `--input-format`.

```bash
# Wrong: unknown extension
cyclonedx-cli analyze --input-file bom.dat

# Correct: specifies format
cyclonedx-cli analyze --input-file bom.dat --input-format json
```

--------------------------------

### Specify Name and Version for Hierarchical Merge

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

Hierarchical merges require both `--name` and `--version` parameters to be specified.

```bash
cyclonedx-cli merge --input-files a.xml b.xml \
    --hierarchical \
    --name MyApp \
    --version 1.0.0
```

--------------------------------

### Add Files to BOM

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Configures options for adding files to a BOM. Scans a directory, computes file hashes, and adds file components to a new or existing BOM. Use when you need to populate a BOM with file details from a filesystem.

```csharp
var options = new AddFilesCommandOptions
{
    NoInput = true,
    OutputFormat = CycloneDXBomFormat.json,
    OutputFile = "bom.json",
    BasePath = "/src",
    Exclude = new List<string> { ".git/**", "node_modules/**" }
};
var result = await AddFilesCommand.AddFiles(options);
```

--------------------------------

### Specify Output Format for Merge Command

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

When merging, if no output file is specified or the output file has an unknown extension, use `--output-format` to define the format.

```bash
# With file
cyclonedx-cli merge --input-files a.xml b.xml \
    --output-file merged.json \
    --output-format json

# To stdout
cyclonedx-cli merge --input-files a.xml b.xml \
    --output-format json
```

--------------------------------

### OutputBomHelper Overload for ConvertFormat

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Writes a BOM to a file or stdout using the specified ConvertFormat and optionally a target specification version.

```csharp
public static async Task<int> OutputBomHelper(Bom bom, ConvertFormat format, SpecificationVersion? outputVersion, string filename)
```

--------------------------------

### Provide Input File or Pipe Data for Validation

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

The `validate` command requires input. Either specify an input file with `--input-file` or pipe data via stdin.

```bash
# Specify file
cyclonedx-cli validate --input-file sbom.xml

# Pipe data
cat sbom.xml | cyclonedx-cli validate --input-format xml
```

--------------------------------

### CycloneDX CLI Format Support

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Information on the input and output formats supported by the CycloneDX CLI, including specification versions.

```APIDOC
## CycloneDX CLI Format Support

### Input/Output Formats

| Format | Read | Write | Notes |
|--------|------|-------|-------|
| XML | ✓ | ✓ | Standard CycloneDX format |
| JSON | ✓ | ✓ | Standard CycloneDX format |
| Protobuf | ✓ | ✓ | Binary format (.cdx, .bin) |
| CSV | ✓ | ✓ | Simplified component list only |
| SPDX JSON | ✓ | ✓ | v2.3 only; conversion may lose data |

### Specification Versions

Supported: v1.0, v1.1, v1.2, v1.3, v1.4, v1.5, v1.6, v1.7 (current)
```

--------------------------------

### Write BOM to File or Stdout

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/utilities.md

Use OutputBomHelper to serialize and write a BOM object to a file or standard output. Supports JSON, XML, and Protobuf formats.

```csharp
public static async Task<int>
    OutputBomHelper(
        Bom bom,
        CycloneDXBomFormat format,
        string filename)
```

```csharp
var bom = new Bom();
// ... populate BOM ...

var result = await CliUtils.OutputBomHelper(
    bom,
    CycloneDXBomFormat.json,
    "output.json");

// result == 0 if successful

// Write to stdout
var result2 = await CliUtils.OutputBomHelper(
    bom,
    CycloneDXBomFormat.xml,
    null);
```

--------------------------------

### SignBomCommand

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Signs an entire CycloneDX XML BOM file with an XML digital signature using an RSA private key.

```APIDOC
## SignBomCommand

### Purpose
Sign BOM files with an RSA private key.

### Entry Point
**Configuration Method**: `SignCommand.Configure(RootCommand rootCommand)`

### Sign BOM Subcommand

### Description
Signs an entire CycloneDX XML BOM with an XML digital signature using an RSA private key.

### Method
`public static async Task<int> SignBom(SignBomCommandOptions options)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **BomFile** (string) - Required - Path to XML BOM file to sign
- **KeyFile** (string) - Optional - Path to RSA private key in PEM format (defaults to "private.key")

### Request Example
```csharp
var bomOptions = new SignBomCommandOptions
{
    BomFile = "sbom.xml",
    KeyFile = "private.key"
};
var result = await SignBomCommand.SignBom(bomOptions);
```

### Response
#### Success Response (0)
Exit code 0 indicates success.

#### Error Response (4)
Exit code 4 indicates unsupported format.

#### Response Example
```
Loading private key...
Loading XML BOM...
Generating signature...
Saving signature...
```
```

--------------------------------

### AutoDetectBomFormat Method

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/types.md

Detects the CycloneDX BOM format from a given filename based on its extension.

```csharp
public static CycloneDXBomFormat AutoDetectBomFormat(string filename)
```

--------------------------------

### Specify Formats for Automation

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

In automated workflows, always explicitly specify input and output formats using '--input-format' and '--output-format' to avoid ambiguity and ensure predictable behavior.

```bash
# Good: formats always explicit
cyclonedx-cli convert \
    --input-file sbom.json \
    --input-format json \
    --output-file sbom.xml \
    --output-format xml

# Risky: relies on extension detection
cyclonedx-cli convert \
    --input-file sbom.json \
    --output-file sbom.xml
```

--------------------------------

### CycloneDX CLI Key Classes

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Overview of key classes used within the CycloneDX CLI, including their responsibilities and methods.

```APIDOC
## CycloneDX CLI Key Classes

This section provides an overview of important classes within the CycloneDX CLI.

### CliUtils

Core I/O utilities.

- **AutoDetectBomFormat**(filename)
- **AutoDetectConvertBomFormat**(filename)
- **InputBomHelper**(filename, format)
- **OutputBomHelper**(bom, format, filename)

### CsvSerializer

CSV format support.

- **Serialize**(bom) → string
- **Deserialize**(csv) → Bom

### Command Classes

Represents the 9 command implementations.

- Static **Configure()** method registers with RootCommand.
- Handler methods are async Task<int>.
```

--------------------------------

### CycloneDX CLI Commands

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/README.md

Reference for the 9 commands available in the CycloneDX CLI tool, including their purpose and key features.

```APIDOC
## CycloneDX CLI Commands

This section details the available commands for the CycloneDX CLI tool.

### Commands Overview

| Command | Purpose | Key Features |
|---------|---------|--------------|
| add | Add files to BOM | File hashing (SHA1/256/384/512), Ant patterns, metadata updates |
| analyze | Analyze BOM | Component version detection, JSON/text output |
| convert | Convert formats | Supports CSV, SPDX, version conversion |
| diff | Generate differences | Version tracking, added/removed/unchanged reporting |
| merge | Merge BOMs | Flat or hierarchical merge, subject metadata |
| validate | Validate against schemas | Auto-detect or explicit version, multiple schemas |
| keygen | Generate key pairs | RSA-2048, PEM format |
| sign | Sign BOMs or files | XML digital signature (BOMs), PKCS#1 RSA-SHA256 (files) |
| verify | Verify signatures | XML signature validation, file signature verification |
```

--------------------------------

### Add Files Subcommand

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Adds file components to a BOM by scanning a directory. It computes file hashes and adds them to the BOM, supporting various input and output formats, and inclusion/exclusion patterns.

```APIDOC
## Add Files Subcommand

### Description
Adds file components to a CycloneDX Bill of Materials (BOM) by scanning a specified directory. This subcommand computes SHA1, SHA256, SHA384, and SHA512 hashes for discovered files and adds them as file components to the BOM. It supports reading from and writing to different formats, and allows for flexible inclusion and exclusion of files using Apache Ant patterns.

### Method
`AddFilesCommand.AddFiles(AddFilesCommandOptions options)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None (Uses options object)

**Options Object**: 
- **InputFile** (string) - Optional - Path to existing BOM file.
- **NoInput** (bool) - When true, creates a new BOM instead of reading an existing one.
- **OutputFile** (string) - Optional - Path to write output BOM (writes to stdout if null).
- **InputFormat** (CycloneDXBomFormat) - Input file format: autodetect, xml, json, protobuf.
- **OutputFormat** (CycloneDXBomFormat) - Output file format: autodetect, xml, json, protobuf.
- **BasePath** (string) - Root directory to scan for files (defaults to current directory).
- **Include** (IList<string>) - Apache Ant patterns for files to include (defaults to all files).
- **Exclude** (IList<string>) - Apache Ant patterns for files to exclude (defaults to none).

### Request Example
```csharp
var options = new AddFilesCommandOptions
{
    NoInput = true,
    OutputFormat = CycloneDXBomFormat.json,
    OutputFile = "bom.json",
    BasePath = "/src",
    Exclude = new List<string> { ".git/**", "node_modules/**" }
};
var result = await AddFilesCommand.AddFiles(options);
```

### Response
#### Success Response (0)
Returns an exit code of 0 indicating success.

#### Response Example
`0`

### Error Handling
- **Exit Code 4**: Parameter validation error (format detection failed).
```

--------------------------------

### Output BOM in Various Formats

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/utilities.md

Helper function to output a BOM object to a file or stdout in specified formats like CSV, SPDX JSON, or CycloneDX JSON. Version specification is ignored for CSV and SPDX formats.

```csharp
public static async Task<int> OutputBomHelper(
    Bom bom, 
    ConvertFormat format, 
    SpecificationVersion? outputVersion, 
    string filename)
```

```csharp
var bom = new Bom();
// ... populate BOM ...

// Output as CSV (version ignored)
var result = await CliUtils.OutputBomHelper(
    bom, 
    ConvertFormat.csv, 
    null, 
    "sbom.csv");

// Output as SPDX JSON (version ignored)
var result2 = await CliUtils.OutputBomHelper(
    bom, 
    ConvertFormat.spdxjson, 
    null, 
    "sbom.spdx.json");

// Output as CycloneDX v1.4 JSON
var result3 = await CliUtils.OutputBomHelper(
    bom, 
    ConvertFormat.json, 
    SpecificationVersion.v1_4, 
    "sbom.json")
```

--------------------------------

### Handle Silent Failures in Pipelines

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/errors.md

When piping commands, explicitly specify input and output formats to prevent silent failures. Relying on file extensions for format detection can be risky.

```bash
# May fail silently if formats not specified
cat bom.json | cyclonedx-cli convert > output.xml

# Better: explicit formats prevent silent failures
cat bom.json | cyclonedx-cli convert --input-format json --output-format xml > output.xml
```

--------------------------------

### Add Build Artifacts to SBOM

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/INDEX.md

Add build artifacts (files) to an SBOM without an input SBOM. This command scans a base path and excludes specified file patterns.

```bash
cyclonedx-cli add files \
    --no-input \
    --base-path ./bin \
    --output-file sbom.json \
    --exclude "*.pdb"
```

--------------------------------

### KeyGenCommand

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/_autodocs/commands.md

Generates a new RSA key pair (2048-bit strength) and exports the public and private keys in PEM format (PKCS#8).

```APIDOC
## KeyGenCommand

### Description
Generates a new RSA key pair with 2048-bit strength and exports the public and private keys in PEM format (PKCS#8).

### Method
`KeyGenCommand.Configure(RootCommand rootCommand)`

### Handler
`public static async Task<int> KeyGen(KeyGenCommandOptions options)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **PrivateKeyFile** (string) - Optional - Output filename for private key (defaults to "private.key")
- **PublicKeyFile** (string) - Optional - Output filename for public key (defaults to "public.key")

### Request Example
```csharp
var options = new KeyGenCommandOptions
{
    PrivateKeyFile = "my-private.key",
    PublicKeyFile = "my-public.key"
};
var result = await KeyGenCommand.KeyGen(options);
```

### Response
#### Success Response (0)
Exit code 0 indicates success.

#### Response Example
```
Generating new public/private key pair...
Saving public key to [filename]
Saving private key to [filename]
```
```

--------------------------------

### Sign BOM Document

Source: https://github.com/cyclonedx/cyclonedx-cli/blob/main/README.md

Sign an entire BOM document using a private key. This command requires the BOM filename and optionally accepts a specific key file.

```bash
cyclonedx sign bom <bom-file> [options]
```