CycloneDX CLI

The CycloneDX CLI is designed for automation. Most commands that accept an --input-file option also support reading from stdin. Similarly, commands with an --output-file option can output to stdout.

Note: When using pipes, you must explicitly specify the --input-format and --output-format because the tool cannot autodetect formats from a stream.

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

CycloneDX CLI requires the .NET Core runtime.

Officially supported builds:

• Windows x64 (win-x64)
• Linux x64 (linux-x64)
• Linux musl x64 (linux-musl-x64, includes Alpine Linux)
• MacOS x64 (osx-x64)

Community supported builds:

• Windows x86 (win-x86)
• Windows ARM x64 (win-arm64)
• Linux ARM (linux-arm)
• Linux ARM x64 (linux-arm64)
• MacOS ARM x64 (osx-arm64)

Platform-specific requirements:

• Windows: .NET Core runtime should be preinstalled.
• Ubuntu: Requires libc6, libgcc1, libgssapi-krb5-2, libicu66, libssl1.1, libstdc++6, and zlib1g.

You can install the CycloneDX CLI using Homebrew on Linux and macOS, or run it directly via Docker.

Homebrew

brew install cyclonedx/cyclonedx/cyclonedx-cli

Docker

You can use the official Docker image: docker run cyclonedx/cyclonedx-cli

The CycloneDX CLI Docker image includes gron, a tool that transforms JSON into discrete assignments. This makes it easier to use grep to find specific data and see the absolute JSON path to a value.

To list all component names and versions from a JSON BOM, pipe the file through gron and filter with grep.

$ 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";

When using the convert command, you can set --output-format to autodetect.

If you use autodetect, you must provide a value for --output-file so the tool can determine the format from the file extension. If you attempt to use autodetect while writing to stdout (by omitting --output-file), the command will fail with a parameter validation error.

# This works because the extension .xml allows autodetection
cyclonedx-cli convert --input-file input.json --output-file output.xml --output-format autodetect

# This will FAIL because stdout has no extension to detect
cyclonedx-cli convert --input-file input.json --output-format autodetect

The validate command can determine the input format in two ways:

1. Explicitly: Using the --input-format flag with xml or json.
2. Autodetect: If --input-format is set to autodetect (or if the format is not specified and the file extension is known), the tool checks the --input-file extension. It supports .json and .xml extensions for autodetect.

Note: If you are piping content via stdin, you must explicitly specify the --input-format because the tool cannot detect the format from a stream without a filename.

If you have an XML format BOM, you must first convert it to JSON using the convert command before piping it to gron for analysis.

$ 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";

The analyze command provides insights into a BOM file.

Key Options:

• --input-file <input-file>: Input BOM filename (reads from stdin if omitted).
• --input-format <autodetect|json|protobuf|xml>
• --output-format <json|text>: Output format (defaults to text).
• --multiple-component-versions: Reports components that appear multiple times with different versions.

# Reporting on components that are included multiple times with different versions:
cyclonedx-cli analyze --input-file sbom.xml --multiple-component-versions

The merge command combines two or more BOMs into one.

Key Options:

• --input-files <input-files>: Space-separated list of input BOM filenames.
• --output-file <output-file>: Destination BOM filename.
• --input-format <autodetect|json|protobuf|xml>
• --output-format <autodetect|json|protobuf|xml>
• --output-version <v1_0|v1_1|v1_2|v1_3|v1_4|v1_5|v1_6|v1_7>
• --hierarchical: Performs a hierarchical merge. Requires all BOMs to have the same subject in their metadata component element. When using this, --name and --version are required.
• --group <group>: Software group name.
• --name <name>: Software name.
• --version <version>: Software version.

# Merge two XML formatted BOMs:
cyclonedx-cli merge --input-files sbom1.xml sbom2.xml --output-file sbom_all.xml

The validate command checks a BOM for specification compliance.

Key Options:

• --input-file <input-file>: Input BOM (reads from stdin if omitted).
• --input-format <autodetect|json|xml>
• --input-version <v1_0|v1_1|v1_2|v1_3|v1_4|v1_5|v1_6|v1_7>: Specification version (defaults to v1.7).
• --fail-on-errors: Returns a non-zero exit code if validation errors are found (useful for CI/CD pipelines).

# Validate BOM and return non-zero exit code:
cyclonedx-cli validate --input-file sbom.xml --fail-on-errors

The convert command allows transformation between CycloneDX XML, JSON, Protobuf, CSV, and SPDX JSON v2.3.

Key Options:

• --input-format <autodetect|csv|json|protobuf|spdxjson|xml>
• --output-format <autodetect|csv|json|protobuf|spdxjson|xml>
• --output-version <v1_0|v1_1|v1_2|v1_3|v1_4|v1_5|v1_6|v1_7>: Specify the CycloneDX specification version (ignored for CSV and SPDX).

Format Notes:

• CSV: A limited representation containing only name and version as required fields.
• SPDX: Conversion to/from SPDX may result in information loss via the CycloneDX.Spdx.Interop library.

# Converting from XML to JSON format:
cyclonedx-cli convert --input-file sbom.xml --output-file sbom.json

# Converting from XML to JSON format and piping output to additional tools:
cyclonedx-cli convert --input-file sbom.xml --output-format json | grep "somthing"