CLI Reference
This page provides a complete reference for all oscal-cli commands and options. For task-oriented guides, see the individual guide pages linked at the bottom.
These options work with any command and control the general behavior of the CLI:
| Option | Description |
|---|---|
--help, -h |
Show help for any command |
--version, -V |
Show version information |
--show-stack-trace |
Show detailed error information |
--quiet, -q |
Suppress non-essential output |
Validate OSCAL documents for well-formedness and schema compliance.
oscal-cli validate [options] <file>
Arguments:
| Argument | Description |
|---|---|
<file> |
Path or URL to OSCAL document |
Options:
| Option | Description |
|---|---|
--as=<format> |
Force input format: xml, json, yaml |
Examples:
# Validate a JSON file
oscal-cli validate ssp.json
# Validate with explicit format
oscal-cli validate --as=json document.txt
# Validate remote file
oscal-cli validate https://example.com/catalog.json
# Validate with detailed errors
oscal-cli validate --show-stack-trace ssp.json
Exit Codes:
| Code | Meaning |
|---|---|
| 0 | Validation passed |
| 1 | Validation failed |
| 2 | Invalid arguments |
Convert OSCAL documents between XML, JSON, and YAML formats.
oscal-cli convert [options] <source> [destination]
Arguments:
| Argument | Description |
|---|---|
<source> |
Input file path or URL |
[destination] |
Output file path (optional, stdout if omitted) |
Options:
| Option | Description |
|---|---|
--to=<format> |
Output format: xml, json, yaml (required) |
--as=<format> |
Input format: xml, json, yaml |
--overwrite |
Overwrite existing output file |
Examples:
# Convert XML to JSON
oscal-cli convert --to=json catalog.xml catalog.json
# Convert to stdout
oscal-cli convert --to=json catalog.xml
# Convert with overwrite
oscal-cli convert --to=json --overwrite catalog.xml catalog.json
Resolve an OSCAL profile to a catalog.
oscal-cli resolve-profile [options] <profile> [catalog]
Arguments:
| Argument | Description |
|---|---|
<profile> |
Input profile file or URL |
[catalog] |
Output catalog file (optional, stdout if omitted) |
Options:
| Option | Description |
|---|---|
--to=<format> |
Output format: xml, json, yaml |
--as=<format> |
Input format: xml, json, yaml |
--overwrite |
Overwrite existing output file |
Examples:
# Resolve profile to JSON catalog
oscal-cli resolve-profile profile.json resolved-catalog.json
# Resolve with format conversion
oscal-cli resolve-profile --to=xml profile.json resolved-catalog.xml
# Resolve to stdout
oscal-cli resolve-profile --to=json profile.xml
Work with Metapath expressions.
Evaluate a Metapath expression against a document.
oscal-cli metapath eval [options] -e <expression> <file>
Arguments:
| Argument | Description |
|---|---|
<file> |
Input file to query |
Options:
| Option | Description |
|---|---|
-e <expression> |
Metapath expression to evaluate (required) |
--to=<format> |
Output format: xml, json, yaml |
Examples:
# Query all controls
oscal-cli metapath eval -e "//control" catalog.json
# Query with JSON output
oscal-cli metapath eval -e "//control/title" --to=json catalog.json
# Count elements
oscal-cli metapath eval -e "count(//control)" catalog.json
Generate shell completion scripts.
oscal-cli shell-completion <shell>
Arguments:
| Argument | Description |
|---|---|
<shell> |
Shell type: bash or zsh |
Examples:
# Generate Bash completion
oscal-cli shell-completion bash > oscal-cli-completion.bash
# Generate Zsh completion
oscal-cli shell-completion zsh > _oscal-cli
The CLI automatically detects the document type by examining the root element. You don't need to specify the document type—validation and conversion work for all types:
| Type | Root Element |
|---|---|
| Catalog | catalog |
| Profile | profile |
| Mapping Collection | mapping-collection |
| System Security Plan | system-security-plan |
| Component Definition | component-definition |
| Assessment Plan | assessment-plan |
| Assessment Results | assessment-results |
| POA&M | plan-of-action-and-milestones |
The CLI determines input format from the file extension. This works for most cases:
| Extension | Format |
|---|---|
.xml |
XML |
.json |
JSON |
.yaml, .yml |
YAML |
Use --as to override detection for files with non-standard extensions.
The CLI respects standard Java environment variables for configuration:
| Variable | Description |
|---|---|
JAVA_HOME |
Java installation directory |
JAVA_OPTS |
JVM options (e.g., -Xmx2g) |
When using Docker, the following tags and options are available:
| Tag | Description |
|---|---|
latest |
Latest stable release |
x.y.z |
Specific version |
develop |
Latest development build |
Mount local directories to make your files accessible inside the container:
# Mount current directory
docker run --rm -v "$(pwd):/data" ghcr.io/metaschema-framework/oscal-cli:latest ...
# Mount specific directory
docker run --rm -v "/path/to/files:/data" ghcr.io/metaschema-framework/oscal-cli:latest ...
For large documents, you may need to increase container memory or CPU limits:
# Limit memory
docker run --rm -m 2g ghcr.io/metaschema-framework/oscal-cli:latest ...
# Limit CPU
docker run --rm --cpus 2 ghcr.io/metaschema-framework/oscal-cli:latest ...
- Installation - Install the CLI
- Validating OSCAL - Validation guide
- Converting Formats - Conversion guide
- Resolving Profiles - Profile resolution guide
- Working with Metaschema - Metapath queries