Getting Started¶

What is OSS IQ?¶

OSS IQ is a tool that maps out open-source packages that your project relies on so you can keep them secure and up to date. It helps move from “CVE panic-fixing”, reactive mode to “planned maintenance” of your entire software supply chain.

Most security tools only alert you when a specific vulnerability (CVE) is found, forcing you to scramble for a “reactive” fix. OSS IQ is different: it looks at your project structure to give you a clear, long-term view of your project dependencies state.

This allows you to build a predictable update rhythm, so you can focus your efforts where they matter most instead of just chasing the latest fire.

How it works¶

The tool scans your project files to identify Direct Dependencies, Dependencies of your direct dpeendencies (Transitive Dependencies), how far behind you are from the latest, safest versions, signs that a library has been abandoned by its creators.

Built for Your Workflow¶

OSS IQ is designed for Platform and Infrastructure teams who need to set standards across many different projects.

You get the data in the format that fits your task:

• Terminal (CLI) “on-the-spot” analysis while you work.

• interactive HTML report For a “bird’s-eye view” of your project’s overall health.

• JSON or CSV Exports to plug data into your automated pipelines or custom spreadsheets.

Quick Start¶

Get OSS IQ up and running in your terminal to analyze your first project.

export OSSIQ_GITHUB_TOKEN=$(gh auth token);

export OSSIQ_GITHUB_TOKEN=replace-with-generated-token;

1. Run your first dependencies analysis

   OSS IQ works best with the popular ecosystem dependency formats e.g. for NPM its package.json or package-lock.json, and for PyPI its pylock.toml, uv.lock, or classic requirements.txt.

   Point ossiq-cli at an existing python or javascript project and OSS IQ will detect proejct dependencies.

   uvx --from ossiq ossiq-cli status testdata/npm/project1/
   

   You always can install ossiq package with respective python tools uv add ossiq or pip install ossiq.

2. Understand the Output

   OSS IQ provides a high-level risk score and breaks down specific signals for both security (vulnerabilities) and maintenance (activity, overhead, and health).

   

   Every table, column, and status marker in this report — including the Transitive Recommendations and Peer Constraint Status sections — is documented in Reference → Console Reports.

Package Details¶

Get a specific package details:

uvx --from ossiq ossiq-cli info sphinx

The section-by-section breakdown of this report — drift status, policy compliance, recommendation rationale, peer requirements, and transitive CVEs — is in Reference → Console Reports.

Gated Package Add¶

ossiq-cli add is a quality-gated alternative to running uv add or npm install directly. It runs the same analysis as info, enforces health gates, and installs the OSS IQ-recommended version — not just the latest one.

# Check health signals and install the recommended version
uvx --from ossiq ossiq-cli add requests

# Pin an exact version yourself (bypasses the solver recommendation)
uvx --from ossiq ossiq-cli add requests --version 2.31.0

# Override critical-warning blocks (use with care)
uvx --from ossiq ossiq-cli add requests --force

Before installing, OSS IQ shows drift status, CVEs, transitive vulnerabilities, and maintainer signals. Packages flagged as critically unhealthy are blocked unless --force is passed.

AI Agent Integration (MCP & Skills)¶

Give your AI coding agent the same health check before it adds or upgrades a dependency. ossiq-cli install skills writes a SKILL.md and registers a local stdio MCP server for Claude Code, OpenAI Codex, and GitHub Copilot.

# Install for all three tools
uvx --from ossiq ossiq-cli install skills

# Or target a single tool
uvx --from ossiq ossiq-cli install skills claude
uvx --from ossiq ossiq-cli install skills codex
uvx --from ossiq ossiq-cli install skills copilot

The command asks for a GitHub token (or takes it via --github-token; leave the prompt blank to skip). The token is stored in ~/.ossiq/config, and in each tool’s MCP server entry where one exists (Claude Code, Codex), so both your own runs and the agent’s runs get the higher API rate limit.

Once installed, the agent can call ossiq-cli info <package> --format agent or the ossiq_evaluate_dependency / ossiq_evaluate_updates MCP tools before touching your dependencies, and get back a compact ok / warn / block verdict. Re-running install skills is safe — it merges into existing config rather than overwriting it.

For exactly which files are written, how the token is stored, and how to run the integration from a local checkout with --dev, see Reference → install skills.

HTML Report¶

1. Generate HTML report:

   uvx --from ossiq ossiq-cli html --output report.html
   

2. Open report.html and you’ll get table view of your dependencies:

3. Click on the Transitive Dependencies tab on the top:

4. Click on a dependency node (blue circle):

From the report you could conclude that vue with version 3.5.38 and that 3.5.38 is the latest version of the package.

Export to JSON or CSV¶

1. Export to JSON:

   uvx --from ossiq ossiq-cli export --output-format=json --output=./scan_export.json .
   

you also could specify schema version via --schema-version argument. We commited to make sure that versions are backward compatible.

2. Export to CSV:

   uvx --from ossiq ossiq-cli export --output-format=csv --output=./scan_export_csv .
   

Note that folder scan_report_csv will be created automatically if it doesn’t exist.