CLI Reference

Every command, flag, and exit code

Commands follow Docker-style conventions: grouped into Common and Management sections. Run primer --help for a grouped overview, or primer <command> --help for per-command usage.

Run primer <command> --help for full flag details.

Common

Command	Description
`primer scan <pkg> --ecosystem <eco>`	Scan a package for known vulnerabilities. Shows "Fixed in:" and a ready-to-run fix command when OSV provides a patched version. Flags: `--version`, `--force`, `--verbose`, `--ai`
`primer scan --file <manifest\|lockfile>`	Audit all packages in an existing manifest or lockfile. Each vulnerable package shows its fix command. Use `--direct-only` to skip transitive deps.
`primer init`	Generate shims in `~/.primer/bin` and prepend to `$PATH`
`primer info`	Show PATH order, shim health, cache stats, and active model (alias for `doctor`)

Management

Command	Description
`primer allow add <pkg> [--ecosystem]`	Add a package to `.primer-ignore` — scanned but never blocked
`primer allow remove <pkg> [--ecosystem]`	Remove a package from the allow-list
`primer allow list`	Print all entries in `.primer-ignore`
`primer cache clear`	Delete all cached vulnerability results
`primer cache stats`	Show entry count, total size on disk, and oldest/newest entry age
`primer config set <key> <value>`	Write a value to `~/.primer/config.toml`. Keys: `ai.backend`, `ai.model`, `ai.tokenizer`, `intercept-restore`, `direct-only`, `prompt-threshold`
`primer config get <key>`	Read a single config value
`primer config list`	Print the full config
`primer model add`	Download the default SmolLM2 model from HuggingFace Hub
`primer model add --from <path>`	Import a local GGUF file (no network)
`primer model add --repo <repo> --file <file>`	Download a specific model from HuggingFace Hub
`primer model list`	List registered models with path and file size
`primer model set <target>`	Set the active inference target. Local: `/path/to/model.gguf`. Ollama: `ollama:llama3.2`
`primer model remove`	Interactive select list of all managed models — choose one or "Remove all"
`primer model remove <name>...`	Remove one or more named models without a prompt
`primer model remove --all`	Remove all managed model files and clear config (non-interactive)
`primer policy list`	Show active rules and expiry status from `.primer/policy.toml` (or `.primer-policy.toml`)
`primer policy check`	Validate policy file syntax without running a scan
`primer migrate`	Move `.primer-ignore`, `.primer-policy.toml`, and `primer-report.json` into `.primer/` and update `.gitignore`
`primer open [<path>]`	Generate a self-contained HTML report from the most recent `report.json` and open it in the default browser
`primer hook install`	Write `.git/hooks/pre-commit` to block vulnerable package additions
`primer hook check`	Scan staged manifest changes manually (also called by the hook itself)
`primer watch [--directory <path>] [--scan]`	Watch manifest files and auto-scan on change. Debounced at 500 ms; exit with `Ctrl+C`
`primer sbom --file <path>`	Emit a Software Bill of Materials. `--format cyclonedx` (default) or `--format spdx`. `--no-scan` skips OSV enrichment
`primer mcp`	Start an MCP server over stdio for AI agent integration
`primer completions <shell>`	Emit a shell completion script. Shells: `bash`, `zsh`, `fish`, `powershell`
`primer uninit [--purge]`	Remove shims and `$PATH` entry. `--purge` also deletes cache and model files

Detailed reference

scan

Scan a package or manifest file against the OSV vulnerability database.

primer scan <package> --ecosystem <eco> [--ai] [--force] [--direct-only] [--verbose]
primer scan --file <manifest> [--format human|sarif] [--output <file>] [--browse]

Flag	Description
`--ecosystem`	Required for single-package scan. Values: `PyPI`, `npm`, `Go`, `Cargo`.
`--file <path>`	Scan all packages in a manifest or lockfile.
`--ai`	Append a local SLM summary to each finding.
`--force`	Proceed regardless of findings. Bypasses the prompt.
`--direct-only`	Skip transitive dependency scanning for this run.
`--verbose`	Show cache hit/miss and fetch source.
`--browse`	Generate an HTML report and open it in the default browser after the scan completes. Requires `--file`.
`--format <fmt>`	Output format. `human` (default) or `sarif`. Requires `--file`.
`--output <file>`	Write output to a file instead of stdout. With `--format sarif`, suppresses human output. Requires `--file`.

init / uninit

primer init [--no-shell]    # generate shims, update PATH
primer uninit [--purge]     # remove shims, strip PATH entry

--no-shell installs shims without modifying any shell rc files. --purge also deletes ~/.primer/cache and ~/.primer/models.

doctor / info

primer doctor    # full health report
primer info      # alias for doctor

Reports: PATH ordering, resolved shim paths, cache size, active AI model, intercept-restore status, active threshold, policy file presence and active/expired rule count. Warns if .primer/ is listed in .gitignore.

allow

Manage the per-project allow-list (.primer-ignore). Allowed packages pass through without a prompt.

primer allow add <pkg> [--ecosystem <eco>]
primer allow remove <pkg> [--ecosystem <eco>]
primer allow list

cache

primer cache stats    # entry count, total size, oldest/newest entry
primer cache clear    # delete all cached scan results

config

primer config set <key> <value>
primer config get <key>
primer config list

Reads and writes ~/.primer/config.toml. See Configuration for all valid keys.

model

primer model add                                    # download default model (SmolLM2-135M GGUF)
primer model add --repo <hf-repo> --file <name>   # download specific model from HF Hub
primer model add --from <path>                      # import a local GGUF
primer model list                                   # show registered models with path + size
primer model set <target>                           # set the active model
primer model remove [<name>...] [--all]            # remove one, several, or all models

Target formats for model set:

Command	Backend
`primer model set ~/.primer/models/smollm2.gguf`	candle (local)
`primer model set ollama:llama3.2`	Ollama HTTP
`primer model set ollama:mistral`	Ollama HTTP

policy

primer policy list    # show active rules and expiry status
primer policy check   # validate policy file syntax

Reads .primer/policy.toml (preferred) or .primer-policy.toml in the current directory. See Policy file for the full schema.

open

primer open [<path>]

Generates a self-contained HTML report from a report.json and opens it in the default browser. No arguments: auto-detects .primer/report.json, then primer-report.json. Pass an explicit path to open any report file.

The report is written to a temp file (primer-report.html) before opening — no server required. The HTML file is standalone and can be shared by email or Slack without any dependencies.

Exits with an error if no report file can be found, or if the OS cannot locate a browser. Also available as primer scan --file <manifest> --browse to open immediately after a file scan.

migrate

primer migrate

One-time migration command. Moves legacy project files into the .primer/ directory:

.primer-ignore → .primer/ignore
.primer-policy.toml → .primer/policy.toml
primer-report.json → .primer/report.json

Uses git mv inside a git repo to preserve history; plain filesystem move otherwise. Updates .gitignore surgically — replaces primer-report.json with .primer/report.json and never adds .primer/ itself. Scans .github/workflows/ for artifact paths that reference the old filenames and prints a warning for each one found.

Note: .primer/policy.toml and .primer/ignore must be committed — they should not appear in .gitignore. Run primer doctor after migration to confirm.

hook

primer hook install    # write .git/hooks/pre-commit in the current repo
primer hook check      # scan staged manifest changes (also called by the hook)

See Git Hooks for full details.

sbom

primer sbom --file <manifest> [--output <file>] [--format cyclonedx|spdx] [--no-scan]

Generates a Software Bill of Materials. Default format is CycloneDX v1.5 JSON. --no-scan emits a pure inventory without OSV enrichment.

watch

primer watch [--directory <path>] [--scan]

Monitors manifest files for changes and re-scans on save (500 ms debounce). --scan runs an immediate scan on startup. Exit with Ctrl+C.

mcp

primer mcp

Starts a Model Context Protocol server over stdio. See MCP Server for setup.

completions

primer completions bash
primer completions zsh
primer completions fish
primer completions powershell

Emits a shell completion script. Pipe to your shell's completion directory:

primer completions zsh > ~/.zsh/completions/_primer

Output behaviour during file scans

Streaming results

primer scan --file prints each package result as its OSV query resolves — you do not wait for the full scan to complete before seeing findings. A running counter shows progress:

[12/48] lodash 4.17.15 — 2 findings
[13/48] express 4.18.1 — clean
[14/48] axios 1.3.0   — 1 finding
...

Order is non-deterministic during the scan (queries resolve in parallel). The final consolidated findings table is always sorted CRITICAL → HIGH → MEDIUM → LOW → UNSCORED.

Terminal hyperlinks

In terminals that support OSC 8 escape sequences (iTerm2, Warp, Windows Terminal, GNOME Terminal), CVE and GHSA IDs are rendered as clickable links to https://osv.dev/vulnerability/<id>. Package names link to their registry pages (npmjs.com, pypi.org, pkg.go.dev, crates.io). Hyperlinks are automatically disabled when stdout is not a TTY (piped output, CI logs, SARIF mode).

Numbered finding navigation

After the audit summary table, primer scan --file offers an interactive navigation prompt when stdin is a TTY:

Enter number for details, [a]ll, [q]uit:

Type a finding number to expand full CVE details for that entry. a loops through all findings in order. q exits with the summary already printed. This prompt is skipped in CI mode (CI=true) and when stdin is not a TTY.

Direct vs transitive findings

When a lockfile is present, findings are grouped:

Direct (2) / Transitive (5)

Direct findings come from packages explicitly listed in the manifest. Transitive findings come from their resolved dependency tree. Use --direct-only to suppress transitive scanning for lower-noise results. Supported lockfiles: package-lock.json, yarn.lock, pnpm-lock.yaml (Node.js); uv.lock, poetry.lock (Python); go.sum (Go); Cargo.lock (Rust).

Exit codes

Code	Meaning
`0`	Clean — no findings at or above `prompt-threshold`.
`1`	Blocked — one or more findings met the threshold and the user chose N (or CI mode auto-blocked).

Environment variables

Variable	Effect
`PRIMER_FORCE=1`	Bypass all prompts and proceed regardless of findings. Equivalent to `--force`.
`PRIMER_AI=0`	Disable AI summaries for this invocation. Useful in CI pipelines.
`PRIMER_CI_MODE=allow-all`	When `CI=true`, scan and log findings but never exit 1. Audit-only mode.
`CI=true`	Activates non-interactive mode automatically. Detected by most CI platforms.