OSCAL CLI

A command-line tool for working with OSCAL (Open Security Controls Assessment Language) and Metaschema content.

The OSCAL CLI is a cross-platform command-line tool that provides essential operations for working with OSCAL documents. Whether you're validating compliance artifacts, converting between formats, or resolving profiles, the CLI offers a straightforward interface that works in interactive sessions and automated pipelines alike.

The CLI is particularly useful for:

• CI/CD integration - Validate OSCAL documents automatically as part of your build pipeline
• Format standardization - Convert OSCAL content to your organization's preferred format
• Profile resolution - Generate resolved catalogs from OSCAL profiles
• Scripting and automation - Incorporate OSCAL processing into shell scripts and workflows
• Learning OSCAL - Experiment with OSCAL documents without writing code

The OSCAL CLI provides a batteries-included approach to OSCAL processing:

• No coding required - Perform common OSCAL operations without writing Java or other code
• Format agnostic - Work with XML, JSON, and YAML interchangeably
• Standards compliant - Built on the same libraries used by NIST for OSCAL reference implementations
• Container ready - Available as a Docker/Podman image for easy deployment
• Cross-platform - Runs anywhere Java runs: Linux, macOS, Windows

For programmatic access to OSCAL functionality, see liboscal-java, the Java library this CLI is built on.

# Validate an OSCAL document
docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest \
    validate /data/ssp.json

# Convert XML to JSON
docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest \
    convert --to=json /data/catalog.xml /data/catalog.json

# Validate an OSCAL document
oscal-cli validate ssp.json

# Convert between formats
oscal-cli convert --to=json catalog.xml catalog.json

# Resolve a profile
oscal-cli resolve-profile profile.json resolved-catalog.json

See the Installation guide for download and setup instructions.

Validate OSCAL documents to ensure they conform to the OSCAL specification. The CLI checks for well-formedness, schema compliance, and optionally validates against Metaschema constraints that express business rules beyond basic schema requirements. Validation errors include detailed messages with line numbers and context to help you quickly identify and fix issues.

Convert OSCAL documents between XML, JSON, and YAML formats with full fidelity. The CLI preserves all data during conversion—you can round-trip documents through multiple format changes without data loss. This is useful for standardizing on a single format across your organization or for working with tools that require a specific format.

Resolve OSCAL profiles to produce flattened catalogs. Profiles define control baselines by selecting controls from catalogs, modifying parameters, and adding organization-specific guidance. Profile resolution produces a “resolved catalog” that incorporates all these customizations into a single, self-contained document.

Query OSCAL content using Metapath, an XPath-like expression language designed for Metaschema-based data. Metapath allows you to extract specific data from documents, count elements, and perform calculations—all from the command line.

Generate XML Schema (XSD) and JSON Schema files from Metaschema module definitions. This is primarily useful for developers working with custom Metaschema models beyond OSCAL.

The CLI is available as a container image:

# Pull the image
docker pull ghcr.io/metaschema-framework/oscal-cli:latest

# Run with mounted volume
docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest \
    validate /data/document.json

See the Installation guide for CI/CD integration examples.

Enable tab completion for Bash or Zsh:

# Bash
mkdir -p ~/.local/share/bash-completion/completions
oscal-cli shell-completion bash > ~/.local/share/bash-completion/completions/oscal-cli

# Zsh
mkdir -p ~/.zsh/completions
oscal-cli shell-completion zsh > ~/.zsh/completions/_oscal-cli

This CLI is part of a larger ecosystem of OSCAL and Metaschema tools:

This project includes plugins for Claude Code that provide AI-assisted development. See the Claude Integration guide for details.

Have questions or found an issue? Here's how to get help:

• GitHub Issues - Report bugs or request features
• Contributing - Contribution guidelines