CLI

The osv CLI is a thin shell front-end over the Go core — ideal for quick lookups, shell scripting, and CI pipelines.

Install

See Quick Start for install options (pre-built binary, go install, or build from source). Pre-built binaries cover:

OS	Architectures
Linux	amd64, arm64, arm (v7)
macOS	amd64, arm64
Windows	amd64, arm64

Download from GitHub Releases.

Commands

How commands map to the core

osv parse

Parse an OSV JSON file and display its fields.

osv parse vulnerability.json           # Key fields (text)
osv parse -v vulnerability.json        # All fields (dates, details, credits, ranges)
osv parse -o json vulnerability.json   # JSON output

Flag	Description
-v, --verbose	Show all fields: published/modified, withdrawn, related, details, credits, per-range events
-o, --output	Output format: text (default) or json

Output includes ID, schema version, summary, aliases/CVE, severity, affected packages, and references.

osv validate

Validate one or more OSV JSON files against the schema (parses, checks required id and schema_version).

osv validate vulnerability.json              # Single file
osv validate file1.json file2.json           # Batch
osv validate -o json vulnerability.json      # JSON output

Exits with code 1 if any file is invalid — friendly for CI gating.

Flag	Description
-o, --output	Output format: text (default) or json

osv filter

Filter by affected package ecosystem, reference type, or alias pattern. At least one filter flag required; flags combine.

osv filter -e PyPI vulnerability.json        # Filter affected by ecosystem
osv filter -r FIX vulnerability.json         # Filter references by type
osv filter -a CVE vulnerability.json         # Filter aliases by pattern
osv filter -e PyPI -r FIX vulnerability.json # Combine
osv filter -o json -e PyPI vulnerability.json

Flag	Description
-e, --ecosystem	Ecosystem name, case-sensitive per OSV spec (PyPI, npm, Maven)
-r, --ref-type	Reference type, auto-uppercased (ADVISORY, FIX, WEB)
-a, --alias	Alias prefix pattern, upper-cased before matching (CVE, GHSA, or CVE-2024 match case-insensitively)
-o, --output	text (default) or json

osv query

Extract focused sub-information. At least one flag required; flags combine.

osv query --severity cvss3 vulnerability.json  # CVSS v3 entry + parsed score (0.0 on a vector string)
osv query --severity cvss2 vulnerability.json  # CVSS v2
osv query --maven vulnerability.json           # Maven groupId/artifactId decomposition
osv query --ranges vulnerability.json          # Version ranges per affected package
osv query --events vulnerability.json          # Event timeline (introduced/fixed/…)
osv query --ranges --events vulnerability.json # Combine

Flag	Description
--severity	cvss3 or cvss2
--maven	Decompose Maven groupId:artifactId
--ranges	Show version ranges
--events	Show event timeline
-o, --output	text (default) or json

TIP

GetScore() returns 0.0 when the OSV score field is a CVSS vector string rather than a number — see Methods.

osv version

osv version

Prints the CLI version (injected at build time by goreleaser) and the supported OSV schema version:

osv-cli version: dev
OSV schema version: 1.4.0

The dev placeholder is replaced with the release tag by goreleaser's ldflags. Unlike the other subcommands, version ignores -o json — it always prints these two text lines.

Global flag

Flag	Description
-o, --output	text (default) or json — applies to parse/validate/filter/query; version ignores it

The -o flag is a persistent (global) flag inherited by every subcommand, but only the four data subcommands actually read outputFormat. Passing -o json to version is silently ignored. An invalid value (e.g. -o yaml) silently falls back to text on the subcommands that read it.

Exit code conventions

Typical pipeline

Composing with jq

Because every subcommand speaks -o json, the CLI drops straight into a Unix pipeline. The -o json output is the same typed core re-marshalled, so field names match the OSV Schema exactly.

# Pull just the CVSS v3 vector string
osv query --severity cvss3 -o json vuln.json | jq -r '.severity.score'

# List every affected ecosystem across a directory, deduplicated
for f in advisories/*.json; do
  osv parse -o json "$f" | jq -r '.affected[].package.ecosystem'
done | sort -u

# Gate CI: fail if any file is invalid, then report the criticals
osv validate advisories/*.json || exit 1
for f in advisories/*.json; do
  osv parse -o json "$f" | jq 'select(.severity != null)'
done

Exit code + JSON compose cleanly

validate sets the exit code (0/1) and can emit JSON, so a single command both gates the pipeline and produces a machine-readable report — no second parse needed.