Commands¶

Every ossiq command, with its arguments, options and exit codes. Part of the reference.

Global options, such as --cooldown-period and --cutoff-date, go before the command: ossiq --cooldown-period 14 status. They are listed with their environment variables in Settings.

Most commands take an optional PROJECT_PATH, which defaults to the current directory.

status¶

ossiq status [OPTIONS] [PROJECT_PATH]

Prints the project report. By default it shows only the packages that need action. status report describes every column and marker.

info¶

ossiq info [OPTIONS] PACKAGE_NAME [PROJECT_PATH]

Prints the report for one package. PACKAGE_NAME matches the package name or its npm alias exactly, ignoring case. For a package that is not installed, info evaluates it as a candidate. info report describes every section.

add¶

ossiq add [OPTIONS] PACKAGE_NAME [PROJECT_PATH]

Shows the package’s CVEs, downloads, maintainers and health warnings, then asks before it installs. Without --version, it installs the recommended version, which is not always the newest. A critical warning blocks the install.

add exits with status 1 when a critical warning blocks it. The Warnings section of the info report lists what counts as critical.

update-context¶

ossiq update-context [OPTIONS] PACKAGE_NAME [PROJECT_PATH]

Compares the installed version of a package with a target version you name, which need not be the one OSS IQ recommends. It reports module-system breaks, engine compatibility and rejected releases along the way, as JSON in the agent format.

plan and apply¶

ossiq plan [OPTIONS] [PROJECT_PATH]
ossiq apply [OPTIONS] [PROJECT_PATH]

plan and apply accept the same options, so a plan previews the matching apply exactly. Update rules describes how each target version is picked.

Both commands exit with status 2 when --override names a package that is not in the project.

An exact pin (==x.y.z) is frozen by default, so an update never moves an intentional pin. --pin-all and --rewrite-versions change how each kind of specifier is written:

To keep every direct dependency pinned, pin once, then upgrade and re-pin in one pass:

ossiq apply --pin-all
ossiq apply --pin-all --rewrite-versions --ignore django

export¶

ossiq export [OPTIONS] [PROJECT_PATH]

Writes the scan to one JSON file. JSON export describes the document.

html¶

ossiq html [OPTIONS] [PROJECT_PATH]

Writes the scan to one self-contained HTML file. HTML report describes what it shows.

install skills¶

ossiq install skills [TOOL] [--via uvx|npx|ossiq] [--dev PATH]

Installs the OSS IQ skill and a local MCP server so AI coding agents check dependency health before they add or update a package. For the task-oriented walkthrough, see Coding agents.

What the command writes¶

All changes are made under your home directory; the command never touches the current project.

The MCP entry registers a local stdio server — the tool launches OSS IQ’s mcp command as a subprocess on your machine, through the same runner the skill uses. No remote service is involved, and nothing is sent anywhere beyond the registry and GitHub API calls a normal scan makes.

The command is idempotent — safe to re-run at any time (for example after switching development mode on or off):

• mcp.json is merged: only the ossiq entry under mcpServers is replaced; every other server entry is preserved.

• The Copilot instructions block is delimited by <!-- ossiq-skill:start --> / <!-- ossiq-skill:end --> markers. On re-run the block between the markers is replaced; the rest of the file — including your own instructions — is untouched.

How the skill runs OSS IQ¶

Every command in the installed skill, and the MCP entry, runs OSS IQ the way you ran install skills. The command prints the result, for example the skill runs ossiq as: npx --yes @ossiq/cli.

A permanent install gets its channel’s runner too: uvx uses a copy installed with uv tool install, and both runners work from any directory. To write a bare ossiq instead, pass --via ossiq. The npx entry needs node on the PATH your MCP client starts servers with.

GitHub login¶

The command writes no GitHub token, either to mcp.json or to a config file. The MCP server uses your GitHub login from the system secret store. Without a login, the first tool call returns a login code for the agent to show you; see Log in through an MCP client. The command prints auth login, through the same runner, as the next step.

Development mode (--dev)¶

When you are working on ossiq itself, --dev <path> points every installed integration at your local checkout instead of the PyPI release:

ossiq install skills claude --dev ~/Projects/ossiq

Two substitutions are made:

• MCP server — registered as uv run --directory <path> ossiq mcp, so the server always runs your current working tree.

• SKILL.md — every command in the skill text runs uvx --from <path> --no-cache ossiq. The --no-cache flag makes uvx rebuild from source on each call, so the agent picks up your edits without a reinstall.

To switch back to the released package, re-run the command without --dev.

auth¶

ossiq auth login [--no-wait | --resume]
ossiq auth status
ossiq auth logout

Logs in to GitHub with a one-time code, through the OAuth device flow. Scans can then make 5,000 GitHub API requests an hour instead of 60. For step-by-step instructions, see Log in to GitHub.

auth exit codes:

Which token a scan uses, where the login is stored and how long it lasts are in GitHub token.

mcp¶

ossiq mcp

Runs a local MCP server over stdio, for a coding agent to start as a subprocess. It takes no options. install skills registers it for you, and MCP tools lists the three tools it serves.

Exit codes¶

Findings never change the exit code: a scan that reports CVEs still exits 0. To gate CI, check the JSON export yourself.

Pass the global --traceback option to print a full traceback in place of the error message.