# How to Get SkillSpector Output in JSON or SARIF Format

> Learn how to get SkillSpector output in JSON or SARIF format using the --format flag with skillspector scan. Easily direct output to files.

- Repository: [NVIDIA Corporation/SkillSpector](https://github.com/NVIDIA/SkillSpector)
- Tags: how-to-guide
- Published: 2026-07-11

---

**Use the `--format` flag with `skillspector scan` to select `json` or `sarif`, and optionally specify `--output` to write to a file instead of stdout.**

NVIDIA's SkillSpector analyzes AI skills for potential issues and can export findings in machine-readable formats. The command-line interface supports both **JSON** and **SARIF** (Static Analysis Results Interchange Format) outputs through a configurable report generation system. This guide covers the exact CLI arguments and implementation details found in the source code to help you integrate SkillSpector into automated workflows.

## Command-Line Format Selection

The `skillspector scan` command accepts a `--format` option that controls the output serialization. According to the CLI implementation in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py), the tool defines a `FormatChoice` enum supporting `terminal`, `json`, `markdown`, and `sarif` values.

When you run a scan, the report node ([`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py)) reads the `output_format` from the execution state. If omitted, it defaults to SARIF. The node then either serializes the raw Python dictionary as JSON or constructs a SARIF 2.1.0 document via the `_build_sarif` method.

### Writing to Files vs. STDOUT

The CLI uses the `_write_result` helper to handle output destination. If you provide `--output /path/to/file`, the content writes to that path using `Path(output).write_text`. Without `--output`, the report prints to the console.

## Generating JSON Output

To export findings as formatted JSON, pass `--format json`. The report node calls `json.dumps(..., indent=2)` on the internal result dictionary, producing a human-readable JSON structure suitable for custom parsing pipelines.

```bash
skillspector scan ./my-skill/ \
    --format json \
    --output report.json

```

If you omit `--output`, the JSON streams to stdout for piping.

## Generating SARIF Output

**SARIF** is the default format when no `--format` is specified. The implementation in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py) constructs a standards-compliant SARIF 2.1.0 object through the `_build_sarif` method, which includes rules metadata, driver information, and findings locations. The payload is validated against the official schema using `skillspector.sarif_models.validate_sarif_report` before output.

```bash
skillspector scan ./my-skill/ \
    --format sarif \
    --output findings.sarif

```

This file integrates with GitHub Code Scanning, VS Code extensions, and other SARIF-compatible tools.

### SARIF with Baseline Suppressions

When using `--baseline` to compare against previous scans, suppressed findings appear in the SARIF output with `"suppressions": [{"kind": "external"}]` annotations, as verified in [`tests/nodes/test_report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/tests/nodes/test_report.py).

```bash
skillspector scan ./my-skill/ \
    --baseline baseline.yaml \
    --format sarif \
    --output sarif-with-baseline.sarif

```

## Implementation Architecture

Understanding the code flow helps troubleshoot format issues:

- **CLI Parsing** ([`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py)): Defines `FormatChoice` enum and `--format` / `--output` arguments
- **Report Generation** ([`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py)): Contains `_build_sarif` and JSON serialization logic
- **Validation** ([`src/skillspector/sarif_models.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/sarif_models.py)): Houses `validate_sarif_report` and the SARIF schema URI

## Summary

- Use `--format json` or `--format sarif` with `skillspector scan` to select your output format
- SARIF is the default when `--format` is omitted
- Specify `--output filename` to write to disk; omit it to print to stdout
- SARIF output is validated against the 2.1.0 schema via `validate_sarif_report`
- Baseline comparisons include suppression metadata in SARIF outputs

## Frequently Asked Questions

### What is the default output format for SkillSpector?

The report node defaults to **SARIF** format when the `--format` argument is not provided, as implemented in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py) where the `output_format` field falls back to the SARIF builder.

### Can I pipe SkillSpector output directly to other tools?

Yes. Omit the `--output` flag to stream the JSON or SARIF payload to stdout. This allows direct piping to tools like `jq` for JSON parsing or submission to security dashboards via command pipelines.

### How does SkillSpector validate SARIF output?

The tool calls `skillspector.sarif_models.validate_sarif_report` after generating the payload in [`src/skillspector/nodes/report.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/nodes/report.py). This ensures the output conforms to the official SARIF 2.1.0 schema before writing to disk or stdout.

### Does the JSON format include the same information as SARIF?

Yes. The JSON output contains the raw Python dictionary of findings with identical data to the SARIF version, just without the SARIF wrapper structure. Both formats include all detected issues, severity levels, and file locations from the scan.