# SkillSpector Scan Exit Codes Explained: A Complete Reference for NVIDIA's CLI

> Understand NVIDIA SkillSpector CLI exit codes 0 1 and 2 for successful scans high risk detections and execution failures. Optimize your CI/CD automation with this complete reference.

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

---

**NVIDIA SkillSpector uses three distinct exit codes—0 for successful low-risk scans, 1 for high-risk detections exceeding the threshold, and 2 for execution failures—to enable reliable automation in CI/CD pipelines.**

NVIDIA SkillSpector is a security scanning tool for AI skill bundles that communicates scan results through standardized exit codes. Understanding these exit codes is essential for integrating SkillSpector into automated workflows and interpreting scan outcomes programmatically. This guide breaks down each exit code based on the implementation in the NVIDIA/SkillSpector source code.

## SkillSpector Exit Code Reference

The `skillspector` CLI, implemented in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py), returns three specific exit codes that indicate scan status:

### Exit Code 0: Success

When a scan completes without errors and the final **risk score** is less than or equal to the **RISK_THRESHOLD** (default 50), SkillSpector exits with code 0. This indicates the skill bundle is considered safe for deployment.

### Exit Code 1: High Risk Detected

Exit code 1 indicates a security concern. The CLI raises `typer.Exit(code=1)` when `(result.get("risk_score") or 0) > RISK_THRESHOLD`, meaning the scan detected vulnerabilities exceeding the acceptable risk threshold.

### Exit Code 2: Execution Error

Exit code 2 covers all failure conditions that prevent the scan from completing. The CLI raises `typer.Exit(code=2)` for `FileNotFoundError` or `ValueError` during input loading, unexpected exceptions during graph execution, or missing optional dependencies when launching the MCP server.

## How Exit Codes Are Determined in the Source Code

The exit code logic resides in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) and depends on the **RISK_THRESHOLD** constant defined in [`src/skillspector/constants.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/constants.py).

### Risk Threshold Comparison

The threshold comparison that determines exit code 1 appears in the CLI driver:

```python
if (result.get("risk_score") or 0) > RISK_THRESHOLD:
    raise typer.Exit(code=1)

```

### Exception Handling for Code 2

File-related and generic exceptions map to exit code 2:

```python
except (FileNotFoundError, ValueError) as e:
    console.print(f"[red]Error:[/red] {e}")
    raise typer.Exit(code=2) from e
except Exception as e:
    # ...

    raise typer.Exit(code=2) from e

```

### Threshold Constant Definition

The threshold value itself is defined in [`src/skillspector/constants.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/constants.py):

```python
RISK_THRESHOLD = 50

```

## Configuring the Risk Threshold

While the default **RISK_THRESHOLD** is 50, this value can be modified in [`src/skillspector/constants.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/constants.py) before building from source. When the risk score produced by the graph execution in [`src/skillspector/graph.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/graph.py) exceeds this threshold, the CLI exits with code 1, signaling that the skill bundle requires review.

## Practical Usage Examples

Checking exit codes in shell scripts:

```bash

# Successful scan (exit code 0)

skillspector scan ./my-skill/
echo $?  # Output: 0

# High-risk detection (exit code 1)

skillspector scan ./suspicious-skill/
echo $?  # Output: 1

# Execution error (exit code 2)

skillspector scan ./nonexistent-path/
echo $?  # Output: 2

```

Integrating into Python automation:

```python
import subprocess

result = subprocess.run(
    ["skillspector", "scan", "my-skill/"],
    capture_output=True,
    text=True
)

if result.returncode == 0:
    print("Scan passed: No high-risk findings")
elif result.returncode == 1:
    print("Scan flagged high risk: Review required")
elif result.returncode == 2:
    print("Scan failed: Check input and dependencies")

```

## Summary

- **Exit code 0** indicates a successful scan with risk score ≤ 50 (safe).
- **Exit code 1** signals high-risk findings when the risk score exceeds **RISK_THRESHOLD**.
- **Exit code 2** represents execution errors including missing files or dependency failures.
- The logic is implemented in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py) using `typer.Exit()`.
- The threshold is defined as **RISK_THRESHOLD = 50** in [`src/skillspector/constants.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/constants.py).

## Frequently Asked Questions

### What does exit code 1 mean in SkillSpector?

Exit code 1 means the scan detected a **risk score** above the configured threshold (default 50), indicating potential security issues in the skill bundle that require manual review before deployment.

### How can I change the threshold that triggers exit code 1?

Modify the **RISK_THRESHOLD** constant in [`src/skillspector/constants.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/constants.py) and rebuild the package, or check if your version supports the `SKILLSPECTOR_RISK_THRESHOLD` environment variable for runtime configuration.

### Why does SkillSpector return exit code 2 when the file exists?

Exit code 2 typically indicates a **ValueError** during input parsing or missing optional dependencies (such as MCP server components) rather than simple file existence. Check the stderr output for specific error details.

### Which source file contains the exit code logic?

The exit code determination logic is implemented in [`src/skillspector/cli.py`](https://github.com/NVIDIA/SkillSpector/blob/main/src/skillspector/cli.py), specifically in the scan command handler that compares the risk score against **RISK_THRESHOLD** and raises `typer.Exit()` with the appropriate code.