Pastoralist

Pastoralist keeps projects more secure while maintaining dependency overrides.

It tracks each override in an appendix: which packages depend on it, when it was first recorded, and whether it can be removed.

Packages you install bring dependencies of their own. Overrides let you choose a different version or replacement package—for example, to address a security issue.

Override Tracking

With an existing qs override, running pastoralist adds this record:

--- package.json
+++ package.json
@@ -5,5 +5,17 @@
   },
   "overrides": {
     "qs": "6.11.2"
+  },
+  "pastoralist": {
+    "appendix": {
+      "[email protected]": {
+        "dependents": {
+          "shepherd-cli": "qs (required by express)"
+        },
+        "ledger": {
+          "addedDate": "2026-10-16"
+        }
+      }
+    }
   }
 }

This example uses express → qs. The dependents and date are generated; the versions shown are fixture inputs.

Quick Start

Install the global CLI with npm or Homebrew:

npm install --global pastoralist
# or
brew install yowainwright/tap/pastoralist

For a project, install it as a dev dependency:

npm install pastoralist --save-dev
npx pastoralist doctor
npx pastoralist

doctor previews changes. Running pastoralist updates the appendix.

Install the bundled agent skill with npx pastoralist init agent-skill. Use npx pastoralist --setup-hook to add it to postinstall.

See the docs for setup, configuration, workspaces, security, and interactive examples.

CLI API

The direct commands below assume pastoralist is available from a project script, global npm install, or Homebrew install. Use npx pastoralist ... for one-off project setup.

pastoralist

Type: command

Updates the target package manifest's override appendix. It reads npm overrides, pnpm pnpm.overrides or pnpm-workspace.yaml (pnpm 11+), Yarn resolutions, and Bun overrides.

pastoralist
pastoralist --dry-run

--help and --version

Type: boolean options

Prints CLI help or the installed package version.

pastoralist --help
pastoralist --version # -v

Check the installed version and available commands before adding Pastoralist to scripts or CI.

--styleguide

Type: boolean option

Opens an interactive radio menu for exploring the Pastoralist DX components without reading or changing project configuration. Use the arrow keys and Enter to choose a demo. In the prompt demo, Space toggles choices, a selects all, n selects none, and Esc cancels.

pastoralist --styleguide

pastoralist doctor

Type: command

Runs a read-only health check. Internally this enables dryRun: true and summary: true.

pastoralist doctor
pastoralist doctor --outputFormat json

pastoralist init

Type: command

Starts the config wizard. The wizard can save config to package.json or an external config file, configure workspace paths, and set up security scanning.

pastoralist init

pastoralist init agent-skill

Type: command

Installs the bundled Pastoralist agent skill into .agents/skills/pastoralist. Existing unmanaged skill files are preserved.

pastoralist init agent-skill

--path, -p

Type: string option Default: "package.json"

Selects the package manifest Pastoralist should read and update.

pastoralist --path packages/app/package.json # -p packages/app/package.json

--root, -r

Type: string option

Sets the root directory used to resolve relative paths, config files, lockfiles, patches, and workspace globs.

pastoralist --root ../my-project # -r ../my-project

--depPaths, -d

Type: string[] option

Scans additional package manifests for monorepo dependency context. Values are collected until the next flag.

pastoralist --depPaths "packages/*/package.json" # -d "packages/*/package.json"

--ignore

Type: string[] option

Excludes package manifests from --depPaths matching.

pastoralist --ignore "**/node_modules/**"

--debug

Type: boolean option

Enables debug logging for CLI execution.

pastoralist --debug

--dry-run

Type: boolean option

Previews changes to project files. Security providers may still write caches.

pastoralist --dry-run

--outputFormat

Type: "text" | "json" option Default: "text"

Selects terminal output or a single machine-readable JSON result.

pastoralist --dry-run --outputFormat json

JSON output includes result status, findings, applied overrides, and metrics.

{
  "success": true,
  "updated": false,
  "overrideCount": 1
}

--summary

Type: boolean option

Prints the metrics table after a text-mode run.

pastoralist --summary

--quiet, -q

Type: boolean option

Suppresses normal text output for CI. Security findings make the command exit with code 1; clean security checks exit with code 0.

pastoralist --quiet --checkSecurity # -q --checkSecurity

--setup-hook

Type: boolean option

Adds pastoralist to the target manifest's postinstall script. Existing postinstall scripts are appended with && pastoralist.

pastoralist --setup-hook

Keeps the appendix current after package installs:

 {
   "scripts": {
-    "postinstall": "build"
+    "postinstall": "build && pastoralist"
   }
 }

--remove-unused

Type: boolean option

Removes verified unused override entries from the active override source and appendix. Preview first with --dry-run.

pastoralist --remove-unused

--checkSecurity

Type: boolean option

Runs vulnerability scanning before the appendix update. Fixable security findings can add override data and security ledger fields.

pastoralist --checkSecurity

Apply fixes with --interactive or --forceSecurityRefactor.

--securityProvider

Type: "osv" | "github" | "snyk" | "npm" | "socket" | "spektion" | string[] option

Chooses one or more security providers. OSV is the default when security is enabled and no provider is set.

pastoralist --checkSecurity --securityProvider osv

--securityProviderToken

Type: string option

Passes a provider token for a single run. Prefer provider environment variables for CI: GITHUB_TOKEN, SNYK_TOKEN, SOCKET_SECURITY_API_KEY, or SPEKTION_API_KEY.

pastoralist --checkSecurity --securityProvider github --securityProviderToken "$GITHUB_TOKEN"

Security Mode Flags

Type: boolean options

Controls how security findings are handled: --interactive prompts for fixes, --forceSecurityRefactor applies compatible transitive fixes without prompting, --hasWorkspaceSecurityChecks includes workspace packages, --promptForReasons asks for manual ledger reasons, and --strict fails on provider errors.

pastoralist --checkSecurity --interactive
pastoralist --checkSecurity --forceSecurityRefactor --strict
pastoralist --checkSecurity --hasWorkspaceSecurityChecks
pastoralist --promptForReasons

Use --interactive for review, --forceSecurityRefactor for unattended fixes, and --strict when provider errors should fail the run.

Direct dependency and devDependency updates require interactive approval and change the original package.json entry. Major upgrades and fixes outside a declared range also require approval. Overrides use the lowest known patched version that resolves the applicable advisories.

Cache Flags

Type: string | number | boolean options

Controls provider cache behavior. --cache-dir changes the cache directory, --cache-ttl sets TTL seconds, --no-cache bypasses reads and writes, and --refresh-cache bypasses reads while writing fresh data.

pastoralist --checkSecurity --cache-dir .cache/pastoralist
pastoralist --checkSecurity --cache-ttl 3600
pastoralist --checkSecurity --no-cache
pastoralist --checkSecurity --refresh-cache

Use these to avoid repeated provider calls, shorten cache windows, or force a fresh advisory lookup.

Thanks

Shout out to Mardin for the conversation, insight, and pairing around this topic.

Made by @yowainwright. MIT, 2022-2026.