Configuration

CLI flags take precedence over package.json settings, which take precedence over external config files. Security settings are deep merged across sources.

Configuration Files

Pastoralist searches for configuration files in this order (first found wins):

1. .pastoralistrc (JSON format)
2. .pastoralistrc.json
3. pastoralist.json
4. pastoralist.config.cjs
5. pastoralist.config.js
6. pastoralist.config.mjs

All external config files use the same top-level Pastoralist settings. Choose the filename by format and convention:

• .pastoralistrc: extensionless rc file parsed as JSON
• .pastoralistrc.json: explicit JSON rc file, and the JSON option created by pastoralist init
• pastoralist.json: visible non-dotfile JSON config
• pastoralist.config.cjs: CommonJS module with module.exports
• pastoralist.config.js: JavaScript config. CommonJS exports are accepted; otherwise it is imported as a module
• pastoralist.config.mjs: ESM module with export default

Use pastoralist.json, not .pastoralist.json.

Example Configurations

Minimal Configuration

Enable security checks with OSV:

{  "checkSecurity": true}

.pastoralistrc.json

{  "checkSecurity": true,  "depPaths": "workspace",  "security": {    "provider": "osv",    "severityThreshold": "medium"  }}

pastoralist.config.js

module.exports = {  depPaths: ["packages/*/package.json", "apps/*/package.json"],  checkSecurity: true,  security: {    provider: "osv",    severityThreshold: "high",    excludePackages: ["@types/*"],  },};

pastoralist.config.mjs

export default {  checkSecurity: true,  depPaths: "workspace",  security: {    provider: "osv",    severityThreshold: "critical",  },};

Configuration Priority

When both external config files and package.json configuration exist, Pastoralist merges them and lets package.json take precedence:

1. External config provides base settings
2. package.json overrides top-level fields
3. Nested objects (like security) are deep merged

Example: Config Merging

.pastoralistrc.json:

{  "checkSecurity": true,  "depPaths": "workspace",  "security": {    "provider": "osv",    "severityThreshold": "medium"  }}

package.json:

{  "pastoralist": {    "security": {      "severityThreshold": "high"    }  }}

Effective configuration:

{  "checkSecurity": true,  "depPaths": "workspace",  "security": {    "provider": "osv",    "severityThreshold": "high"  }}

Configuration Options

Top-Level Options

Security Configuration

The security object supports the following options:

Best-Case Portfolio Configuration

Enable bestCase to rank candidate version combinations under one policy. The built-in evaluator checks advisory data for the candidate state; it does not materialize a lockfile or resolve peer compatibility. Supply an API bestCaseEvaluator when the project needs those checks.

{  "pastoralist": {    "checkSecurity": true,    "bestCase": {      "enabled": true,      "userOwnedOverrides": ["alpha"],      "riskAggregation": "both",      "objectives": [        "known-exploited",        "critical",        "high",        "expected-exploitation",        "package-exposures",        "compatibility",        "change-count",        "oldness"      ],      "search": {        "mode": "auto",        "exactStateLimit": 256,        "beamWidth": 16,        "maxEvaluations": 1000      }    }  }}

Objectives are compared in array order; Pastoralist does not combine them into a weighted sum. Supported objectives are known-exploited, critical, high, medium, low, expected-exploitation, package-exposures, compatibility, change-count, and oldness.

An exact search reports provenOptimal: true only when it evaluates every state. Beam search and capped exact search report provenOptimal: false.

Workspace Paths and External Sources

depPaths: "workspace" reads patterns from package.json#workspaces and pnpm-workspace.yaml. Use explicit package manifest globs for other layouts. See Workspaces for package-manager examples.

overrideSource reads and writes overrides from a separate JSON or YAML file. For pnpm 11+, Pastoralist resolves pnpm-workspace.yaml automatically. appendixSource writes the appendix to a JSON config file or .pastoralistrc.

{  "pastoralist": {    "overrideSource": "config/overrides.json",    "appendixSource": ".pastoralistrc.json"  }}

Security Tracking

Expanded appendix entries include ledger.addedDate. Security fixes can add CVE, severity, provider, and vulnerable-range metadata to that ledger:

{  "pastoralist": {    "appendix": {      "[email protected]": {        "dependents": {          "my-app": "lodash@^4.17.0"        },        "ledger": {          "addedDate": "2026-05-30T00:00:00.000Z",          "reason": "Security vulnerability CVE-2021-23337",          "source": "security",          "securityChecked": true,          "securityCheckDate": "2026-05-30T00:00:00.000Z",          "securityCheckResult": "clean",          "securityProvider": "osv",          "cves": ["CVE-2021-23337"],          "cveDetails": [            {              "cve": "CVE-2021-23337",              "severity": "high",              "patchedVersion": "4.17.21"            }          ],          "severity": "high",          "vulnerableRange": "<4.17.21",          "patchedVersion": "4.17.21",          "keep": true        }      }    }  }}

With compactAppendix: true, routine entries can use top-level addedDate instead of a ledger. Entries with reasons, security data, patches, or keep constraints stay expanded.

Ledger Fields

• addedDate: Date recorded when the entry was first written
• reason: Why the override was needed. Accepts a non-empty string, a ProjectReason, or a BestCaseReason
• source: How the entry was created — "manual" or "security"
• securityChecked: Whether a security check was performed
• securityCheckDate: When the last security check occurred
• securityCheckResult: Result of the last check — "clean", "error", or "skipped"
• securityProvider: Which provider detected the vulnerability
• cves: All CVE identifiers related to this vulnerability
• cveDetails: Per-CVE objects with cve, severity, and patchedVersion
• severity: Highest severity across all CVEs (low, medium, high, critical)
• vulnerableRange: Semver range that is affected
• patchedVersion: Version that resolves the vulnerability
• keep: Prevent --remove-unused from removing this entry. Set to true or a KeepConstraint object

Structured Ledger Reasons

Use a project reason for an engineer-selected pin or patch:

{  "reason": {    "type": "project",    "summary": "Keep the patched fork until upstream publishes a release.",    "pin": "2.4.1",    "patch": "patches/example+2.4.1.patch",    "constraints": ["Requires the current plugin API"],    "references": ["https://example.com/upstream/issue/123"]  }}

summary is required. pin, patch, constraints, and references are optional and descriptive; package-manager overrides and appendix patch paths remain authoritative.

Best-case selection writes a reason tied to the complete portfolio decision:

{  "reason": {    "type": "best-case",    "summary": "Selected as part of the lowest-risk dependency portfolio",    "decisionId": "best-case-4b825dc642cb",    "policyHash": "d14a028c2a3a2bc9",    "search": {      "evaluatedStates": 64,      "provenOptimal": true    },    "impact": {      "fixedVulnerabilities": 3,      "introducedVulnerabilities": 0,      "remainingVulnerabilities": 1    }  },  "cves": ["CVE-2026-1234"]}

The reason belongs to one dependency item. Dependencies selected by the same portfolio share a decisionId. CVEs remain in the sibling cves field.

Keeping Overrides with keep

To pin an override so --remove-unused never removes it, set keep: true on the ledger:

{  "ledger": {    "addedDate": "2026-05-30T00:00:00.000Z",    "keep": true  }}

To keep an override until a date or version is reached, use a KeepConstraint object:

{  "ledger": {    "addedDate": "2026-05-30T00:00:00.000Z",    "keep": {      "reason": "Waiting for upstream patch",      "until": "2027-06-01",      "untilVersion": "4.18.0"    }  }}

KeepConstraint fields:

• reason (required): Why this override is being kept
• until: ISO date after which the keep is considered expired
• untilVersion: Semver. The keep expires once the root dependency meets or exceeds this version
• reviewBy: Freeform field for tracking who should review the decision

This shows which packages were overridden for security reasons and when they were last checked.

JavaScript Config Files

Use pastoralist.config.cjs for CommonJS or pastoralist.config.mjs for ESM:

export default {  checkSecurity: true,  depPaths: "workspace",  security: {    provider: "osv",    severityThreshold: "high",  },};

TypeScript config files are not loaded directly. Use JSON, CJS, JS, or MJS config files.

Migration from CLI Flags

If you're currently using CLI flags, you can migrate to config files:

Before (CLI flags)

pastoralist --checkSecurity --depPaths "packages/*/package.json"

After (config file)

{  "checkSecurity": true,  "depPaths": ["packages/*/package.json"]}

pastoralist

CLI flags still work and will override config file settings.