Configuration

All settings live in ~/.primer/config.toml

The file is created on first write. You never need to edit it by hand — use primer config set <key> <value> instead. Keys that are not set use their defaults; primer config list only shows keys you have explicitly changed.

Managing config

primer config set prompt-threshold medium   # write a value
primer config get prompt-threshold          # read one key
primer config list                          # print all set keys

Key reference

Key	Type	Default	Description
`prompt-threshold`	string	`"high"`	Minimum severity that triggers a prompt or CI block. Values: `critical`, `high`, `medium`, `low`.
`intercept-restore`	bool	`false`	When `true`, bare restore commands (`npm install` with no args, `pip install` with no args, `go mod download`) are scanned against the project manifest before execution.
`direct-only`	bool	`false`	Skip transitive dependency scanning. Only direct packages are checked. Useful when scan latency is a concern.
`ai.backend`	string	—	Inference backend: `"local"` (candle GGUF) or `"ollama"` (HTTP to `localhost:11434`).
`ai.model`	string	—	For `local`: absolute path to a `.gguf` file. For `ollama`: model name, e.g. `llama3.2`.
`ai.tokenizer`	string	—	Absolute path to `tokenizer.json`. Only used when `ai.backend = "local"`.

Policy file

.primer-policy.toml is a per-project file committed to the repo. It travels with the codebase and is enforced by every developer machine and CI job automatically — no flags required.

It is distinct from ~/.primer/config.toml (machine-wide settings) and .primer-ignore (per-package allow-list).

Schema

[policy]
threshold = "high"          # optional global override for this repo

[[deny]]
package = "event-stream"    # hard block by name regardless of CVE status
reason  = "supply chain compromise"

[[ignore]]
cve     = "CVE-2023-1234"
package = "pillow"          # optional: scope to one package
expires = "2026-12-31"      # optional YYYY-MM-DD; finding re-activates after this date
reason  = "Mitigated by WAF"

[[override]]
package   = "requests"
threshold = "critical"      # use a stricter or looser threshold for this package

Rule evaluation order

[[deny]] — hard block by package name; no CVE required.
[[ignore]] — suppress a specific CVE. Expired rules re-activate the finding with a warning.
[[override]] — per-package threshold replaces the global one.
Global [policy] threshold or prompt-threshold from config.toml.

Commands

primer policy list    # show all rules and expiry status
primer policy check   # validate syntax without scanning

Severity threshold

Controls which findings block an install or CI job.

Value	Severities that block
`critical`	CRITICAL only
`high` (default)	CRITICAL, HIGH
`medium`	CRITICAL, HIGH, MEDIUM
`low`	All severities

primer config set prompt-threshold medium   # block MEDIUM and above
primer config set prompt-threshold critical # block CRITICAL only

Intercept bare restore

Disabled by default to avoid surprising slowdowns. Enable when you want bare npm install or pip install in a project directory to trigger a full manifest scan first.

primer config set intercept-restore true

AI configuration

Set after running primer model add or primer model set — those commands write these keys automatically. Only edit directly if you are registering an external path or an Ollama target.

# local GGUF
primer model set ~/.primer/models/smollm2.gguf

# Ollama
primer model set ollama:llama3.2

Resulting ~/.primer/config.toml:

[ai]
backend   = "local"
model     = "/Users/you/.primer/models/smollm2.gguf"
tokenizer = "/Users/you/.primer/models/tokenizer.json"

.primer/ project config directory

primer looks for project-level files in .primer/ first, then falls back to legacy root-level filenames with a deprecation warning:

New path	Legacy fallback	Notes
`.primer/policy.toml`	`.primer-policy.toml`	Commit to repo; must not be gitignored
`.primer/ignore`	`.primer-ignore`	Commit to repo; must not be gitignored
`.primer/report.json`	`primer-report.json`	Generated output; add to `.gitignore`

Run primer migrate once per repository to move legacy files and update .gitignore automatically.

primer migrate

Until you migrate, primer reads the legacy filenames and prints a one-time deprecation warning per file. After migration, the legacy filenames are ignored.

primer doctor warns if .primer/ is listed in .gitignore. primer hook check exits 1 if .primer/policy.toml or .primer/ignore are gitignored.

CI artifact integration

Upload both the JSON report and the generated HTML as workflow artifacts so findings are always browseable from the Actions run:

- name: Scan dependencies
  uses: barestripehq/primer-action@v1

- name: Upload security report
  if: always()
  uses: actions/upload-artifact@v7
  with:
    name: primer-report
    path: |
      .primer/report.json
      primer-report.html

Generate the HTML artifact in CI with primer open after the scan step:

- name: Generate HTML report
  if: always()
  run: primer open .primer/report.json

The HTML file is self-contained — no server required. Share it directly from the artifact zip.

Diagnostics

primer doctor      # shows active threshold, intercept-restore status, model path