CLI Mode Deployment Guide

Install and use OSCAL CLI as a standalone command-line tool for automation, scripting, and CI/CD pipelines.

Version: 1.0.0 · Updated: October 26, 2025

Overview

The OSCAL CLI is a standalone command-line tool for working with OSCAL documents without requiring a web interface or database. Perfect for automation, batch processing, CI/CD pipelines, and offline use.

What You Get

Command-Line Tool — oscal-cli executable for all OSCAL operations
All OSCAL Models — Catalog, Profile, SSP, Component Definition, AP, AR, POA&M
Format Conversion — Convert between XML, JSON, and YAML
Profile Resolution — Resolve profiles to catalogs
Schema Validation — Validate against OSCAL schemas and constraints
Batch Operations — Process multiple files with shell scripts

No web interface, database, or user authentication required. Works 100% offline after installation.

NOT Included in CLI Mode

Web interface (no browser UI)
User authentication or multi-user support
Database for storing files or history
REST API endpoints

For web interface and API features, see Local Deployment or Azure Deployment.

Quick Start (2 Minutes)

Mac/Linux

# 1. Download and run the installer
curl -fsSL https://raw.githubusercontent.com/RegScale/oscal-hub/main/installer/install.sh | bash

# 2. Add to PATH (if not already done)
export PATH="$PATH:$HOME/.oscal-cli/bin"

# 3. Verify installation
oscal-cli --version

# 4. Validate an OSCAL file
oscal-cli catalog validate examples/catalog.json

Windows (PowerShell)

# 1. Allow script execution (if needed)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 2. Download and run installer
Invoke-WebRequest -Uri https://raw.githubusercontent.com/RegScale/oscal-hub/main/installer/install.ps1 -OutFile install.ps1
.\install.ps1

# 3. Add to PATH or use full path
%USERPROFILE%\.oscal-cli\bin\oscal-cli.bat --version

# 4. Validate an OSCAL file
oscal-cli catalog validate examples\catalog.json

Prerequisites

Required Software

Java 11 or higher (Java 21 LTS recommended)

# Check your Java version
java -version
# Expected: openjdk version "11.0.0" or higher

Mac: brew install openjdk@21 or download from Adoptium
Linux: sudo apt install openjdk-21-jdk
Windows: winget install EclipseAdoptium.Temurin.21.JDK

System Requirements

Requirement	Minimum	Recommended
RAM	512 MB	2 GB
Disk Space	100 MB	500 MB
CPU	1 core	2+ cores
Network	Only required for initial installation	—

Installation Methods

Method 1: Automated Installer (Recommended)

The automated installer is the easiest way to get started. It checks for Java, downloads the latest OSCAL CLI, and sets everything up.

# Mac/Linux
curl -fsSL https://raw.githubusercontent.com/RegScale/oscal-hub/main/installer/install.sh | bash

# Or download first, then run
curl -O https://raw.githubusercontent.com/RegScale/oscal-hub/main/installer/install.sh
chmod +x install.sh
./install.sh

# Custom installation directory
OSCAL_CLI_HOME=/opt/oscal-cli ./install.sh

# Install specific version
OSCAL_CLI_VERSION=1.0.3 ./install.sh

Method 2: Manual Installation

Download from Maven Central and extract manually:

# Download latest version (example: 1.0.3)
wget https://repo1.maven.org/maven2/gov/nist/secauto/oscal/tools/oscal-cli/cli-core/1.0.3/cli-core-1.0.3-oscal-cli.zip

# Extract to installation directory
mkdir -p ~/.oscal-cli
unzip cli-core-1.0.3-oscal-cli.zip -d ~/.oscal-cli

# Add to PATH
echo 'export PATH="$PATH:$HOME/.oscal-cli/bin"' >> ~/.bashrc
source ~/.bashrc

Method 3: Build from Source

For developers or those who want the latest unreleased version:

# Clone repository
git clone https://github.com/RegScale/oscal-hub.git
cd oscal-cli

# Build with Maven
cd cli
mvn clean install

# Run from build output
./target/appassembler/bin/oscal-cli --version

Using the CLI

Command Structure

oscal-cli <model> <operation> [options] <file>

<model> — OSCAL model type (catalog, profile, ssp, etc.)
<operation> — What to do (validate, convert, resolve)
[options] — Flags like --to, --as, --overwrite
<file> — Input file path

Common Operations

Validation

# Validate a catalog
oscal-cli catalog validate my-catalog.xml

# Validate a profile
oscal-cli profile validate my-profile.json

# Validate an SSP
oscal-cli ssp validate my-ssp.yaml

Format Conversion

# XML to JSON
oscal-cli catalog convert --to json catalog.xml catalog.json

# JSON to YAML
oscal-cli profile convert --to yaml profile.json profile.yaml

# YAML to XML
oscal-cli ssp convert --to xml ssp.yaml ssp.xml

Profile Resolution

# Resolve profile to JSON catalog
oscal-cli profile resolve --to json my-baseline.xml resolved-catalog.json

# Resolve profile to XML catalog
oscal-cli profile resolve --to xml my-baseline.json resolved-catalog.xml

Getting Help

# General help
oscal-cli --help

# Model-specific help
oscal-cli catalog --help
oscal-cli profile --help

# Operation-specific help
oscal-cli catalog validate --help
oscal-cli profile resolve --help

Common Workflows

Validate All Files in a Directory

# Bash (Mac/Linux)
for file in catalogs/*.xml; do
    echo "Validating $file..."
    oscal-cli catalog validate "$file"
done

# PowerShell (Windows)
Get-ChildItem *.json | ForEach-Object {
    Write-Host "Validating $_..."
    oscal-cli profile validate $_.Name
}

Batch Format Conversion

# Convert all XML catalogs to JSON
for file in *.xml; do
    output="${file%.xml}.json"
    oscal-cli catalog convert --to json "$file" "$output" --overwrite
done

Git Pre-Commit Hook

Create .git/hooks/pre-commit:

#!/bin/bash
echo "Validating OSCAL files..."

OSCAL_FILES=$(git diff --cached --name-only | grep -E '\.(xml|json)$')

for file in $OSCAL_FILES; do
    if ! oscal-cli catalog validate "$file"; then
        echo "✗ Validation failed for $file"
        exit 1
    fi
done

echo "✓ All OSCAL files validated successfully"

CI/CD Integration

GitHub Actions

Create .github/workflows/validate-oscal.yml:

name: Validate OSCAL Files

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: Install OSCAL CLI
        run: |
          curl -fsSL https://raw.githubusercontent.com/RegScale/oscal-hub/main/installer/install.sh | bash
          echo "$HOME/.oscal-cli/bin" >> $GITHUB_PATH

      - name: Validate OSCAL files
        run: |
          for file in oscal/**/*.{xml,json}; do
            oscal-cli catalog validate "$file"
          done

GitLab CI

Create .gitlab-ci.yml:

image: eclipse-temurin:21-jdk

validate_oscal:
  script:
    - curl -fsSL https://raw.githubusercontent.com/RegScale/oscal-hub/main/installer/install.sh | bash
    - export PATH="$PATH:$HOME/.oscal-cli/bin"
    - for file in oscal/**/*.xml; do oscal-cli catalog validate "$file"; done

Troubleshooting

Command Not Found

Symptom: oscal-cli: command not found

# Add to PATH
export PATH="$PATH:$HOME/.oscal-cli/bin"
echo 'export PATH="$PATH:$HOME/.oscal-cli/bin"' >> ~/.bashrc
source ~/.bashrc

# Or use full path
~/.oscal-cli/bin/oscal-cli --version

Java Not Found or Wrong Version

Symptom: Error about Java not installed or Java 11+ required

Install Java 21 from Adoptium
Verify: java -version
Set JAVA_HOME if needed

Out of Memory

Symptom: java.lang.OutOfMemoryError

# Increase Java heap size
export JAVA_OPTS="-Xmx4g"
oscal-cli catalog validate large-catalog.xml

# For very large files
export JAVA_OPTS="-Xmx8g"

Validation Fails

Symptom: Document fails validation with schema errors

Review error messages — they indicate specific OSCAL schema violations
Common issues: missing required fields, invalid UUIDs, incorrect nesting
Refer to OSCAL documentation for model requirements

Next Steps

After successful CLI installation:

Read the User Guide
Try validating OSCAL documents with the CLI
Set up batch processing scripts for your workflow
Integrate into your CI/CD pipeline
Consider Local Deployment for the web interface
Explore Azure Deployment for production