CLI Tool

The Ossprey CLI lets you run scans directly from your terminal, making it easy to integrate into local development workflows and CI/CD pipelines. It is distributed as a Python package called ossprey and is available on  PyPI .
﻿
InstallationRequires Python 3.12 or above. If you need support for other versions, please  raise an issue  on GitHub.
Install the CLI via pip:
pip install ossprey
Once installed, verify it is working by running:
python -m ossprey --help
You can also invoke it directly if the script entrypoint is on your PATH:
ossprey --help
﻿
Ossprey cli help menuOssprey cli help menu
﻿
﻿
AuthenticationThe CLI requires an API key to submit scans to the Ossprey service. You can provide your key in one of two ways:
Command-line flag — pass --api-key YOUR_KEY directly when invoking a scan.
Environment variable — set API_KEY in your shell environment (useful for CI/CD).
If no API key is provided and you are not using a dry-run mode, the CLI will exit with an error.
For details on generating and managing your API key, see the Security & API Keys page.
﻿
Commands referenceThe CLI is invoked with python -m ossprey (or simply ossprey). All configuration is provided through flags and environment variables — there are no sub-commands.
Core flags
Flag
Env Variable
Description
Default
--package / --dir
INPUT_PACKAGE
Path to the package or directory to scan.
Current working directory
--api-key
API_KEY
Your Ossprey API key. Required unless using a dry-run mode.
None
--mode
INPUT_MODE
SBOM generation strategy. Options: auto, pipenv, python-requirements, poetry, npm, yarn, fs.
auto
--url
INPUT_URL
Ossprey API endpoint URL. You should not need to change this.
https://api.ossprey.com
-o / --output
INPUT_OUTPUT
Write the resulting SBOM to a JSON file at this path.
None (no file written)
-v / --verbose
INPUT_VERBOSE
Enable verbose logging, including full stack traces on errors.
Off
--soft-error
INPUT_SOFT_ERROR
Errors are logged but the process exits with code 0 instead of 1. Useful in CI/CD when you don't want a scan failure to block your pipeline.
Off
--dry-run-safe
INPUT_DRY_RUN_SAFE
Run locally without calling the Ossprey API. Generates the SBOM and reports no vulnerabilities. No API key required.
Off
--dry-run-malicious
INPUT_DRY_RUN_MALICIOUS
Same as --dry-run-safe but injects a fake test vulnerability into the first component. Useful for testing alerting and CI/CD failure behaviour.
Off
--github-comments
INPUT_GITHUB_COMMENTS
When running in GitHub Actions on a pull request, post scan results as PR review comments.
Off
Scan modesWhen --mode is set to auto (the default), the CLI inspects the target directory and automatically detects which package managers are in use based on the presence of lock files and manifests:
requirements.txt → python-requirements
pyproject.toml or poetry.lock → poetry (falls back to pipenv if the project is not a valid Poetry project or Poetry is not installed)
package.json or package-lock.json → npm
yarn.lock → yarn
If no recognised package manager files are found in auto mode, the CLI will exit with an error. You can override this by explicitly setting --mode fs to perform a filesystem-level scan.
PIC-TODO: Graphic — a visual diagram showing the auto-detection logic: directory files on the left (requirements.txt, pyproject.toml, package.json, yarn.lock) with arrows pointing to the detected mode on the right. Makes the auto-detect behaviour easy to understand at a glance.
Usage examplesScan the current directory (auto-detect mode):
ossprey --api-key YOUR_KEY
Scan a specific directory with a particular mode:
ossprey --api-key YOUR_KEY --package ./my-project --mode npm
Dry run to test your setup (no API key needed):
ossprey --dry-run-safe --package ./my-project -v
Save the SBOM to a file:
ossprey --api-key YOUR_KEY -o sbom-output.json
﻿
Exit codesThe CLI uses exit codes to communicate scan outcomes, which is important for CI/CD integration:
Exit 0 — scan completed successfully with no malicious packages detected, or --soft-error was set.
Exit 1 — a malicious package was found, or the scan failed due to an error (missing API key, no package manager detected, API timeout, etc.).
﻿
CI/CD integrationGitHub ActionsThe Ossprey CLI works as a step in any GitHub Actions workflow. Here is an example that scans your repository on every pull request:
name: Ossprey Scan
on:
  pull_request:
    branches: [main]
﻿
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
﻿
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
﻿
      - name: Install Ossprey
        run: pip install ossprey
﻿
      - name: Run Ossprey Scan
        env:
          API_KEY: ${{ secrets.OSSPREY_API_KEY }}
        run: ossprey --github-comments
Store your API key as a  GitHub Actions secret  called OSSPREY_API_KEY. Never hard-code your key in a workflow file.
﻿
The Github Action Check for Malware in your pull requestThe Github Action Check for Malware in your pull request
When --github-comments is enabled and the workflow is triggered by a pull request, the CLI will post inline review comments on the PR highlighting any malicious packages found, as well as a summary comment on the PR thread.
﻿
An Ossprey Alert from a Github ActionAn Ossprey Alert from a Github Action
Using the soft-error flag in pipelinesIf you want Ossprey to report results without blocking your pipeline (for example, during an initial rollout), add the --soft-error flag. The CLI will log any issues but will always exit with code 0.
Other CI/CD systemsThe CLI works in any environment that supports Python 3.12+. Set the API_KEY environment variable and run ossprey as a build step. All flags have corresponding INPUT_* environment variable equivalents (see the flags table above), making it easy to configure through your CI system's environment variable settings.
﻿