Building from Source

This guide explains how to build the OSCAL CLI from source code.

Ensure JAVA_HOME is set correctly:

# macOS
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

# Linux (adjust path to your installation)
export JAVA_HOME=/usr/lib/jvm/java-17-openjdk

# Windows
set JAVA_HOME=C:\Program Files\Java\jdk-17

Clone the repository with submodules:

git clone --recurse-submodules https://github.com/metaschema-framework/oscal-cli.git
cd oscal-cli

If you already cloned without submodules, initialize them:

git submodule update --init --recursive

Build and install to your local Maven repository:

mvn install

This produces the CLI distribution in target/oscal-cli-enhanced-*-oscal-cli.zip.

mvn test

# Run a single test class
mvn test -Dtest=CLITest

# Run a single test method
mvn test -Dtest=CLITest#testValidate

mvn install -DskipTests

Replicate the full CI/CD build (recommended before pushing):

mvn install -PCI -Prelease

This enables additional checks including:

• License header verification
• Checkstyle code style checks
• SpotBugs static analysis
• Full test suite

mvn license:check

mvn formatter:format

mvn checkstyle:check

After building, you can run the CLI directly:

# Extract the distribution
unzip target/oscal-cli-enhanced-*-oscal-cli.zip -d target/cli

# Run the CLI
target/cli/bin/oscal-cli --help

To build a local container image:

# Build with Docker
docker build -t oscal-cli:local .

# Test the image
docker run --rm oscal-cli:local --help

To build the project documentation site:

mvn site

The generated site appears in target/site/.

Symptom: Build fails with missing OSCAL or Metaschema files.

Solution: Initialize submodules:

git submodule update --init --recursive

Symptom: Compilation errors or “unsupported class file version” errors.

Solution: Ensure you're using Java 17 or later for building:

java -version
mvn -version

Symptom: Build fails with plugin compatibility errors or enforcer rule failures.

Solution: Upgrade Maven to 3.9.0 or later:

mvn -version

Symptom: Build fails with OutOfMemoryError.

Solution: Increase Maven's heap size:

export MAVEN_OPTS="-Xmx2g"
mvn install

For contribution guidelines, including code style requirements and the pull request process, see CONTRIBUTING.md.

• Installation - Install the pre-built CLI
• CLI Reference - Complete command reference