Skip to content

About

keep your projects more secure & maintain dependency overrides with 1 command πŸ‘©πŸ½β€πŸŒΎ

Topics

Resources

Code of conduct

Security policy

Stars

112 stars

Watchers

1 watching

Forks

Repository files navigation

Pastoralist icon

Pastoralist

Socket Badge npm version npm downloads CI OpenSSF Scorecard codecov

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": {
+      "qs@6.11.2": {
+        "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.

Python: uv override tracking

In a standalone uv project, run pastoralist to track existing tool.uv.override-dependencies. Pastoralist detects pyproject.toml with uv.lock or uv settings and writes its appendix to .pastoralistrc. No package.json is required. The Python manifest and lockfile remain unchanged; --dry-run previews the appendix update.

When both Python and JavaScript project files are present, select --path pyproject.toml or --path package.json. Existing entries for the unselected ecosystem remain in the appendix. JavaScript configuration files must set appendixSource to a separate JSON file when tracking uv overrides.

This first slice supports global string overrides, one per normalized package name. Dependency paths come from the lockfile snapshot; absent paths remain unknown until native verification is available. Workspaces, scoped overrides, security checks, automatic fixes, and removal are not supported yet.

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 available transitive fixes without prompting, --hasWorkspaceSecurityChecks includes workspace packages, --promptForReasons asks for manual ledger reasons, and --strict fails on unresolved vulnerabilities or provider permission errors.

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

Direct dependency updates require interactive approval. Forced transitive fixes may cross major versions and parent ranges. Overrides select the lowest known patched version resolving the advisories. Reinstall dependencies and rescan after fixes.

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.

About

keep your projects more secure & maintain dependency overrides with 1 command πŸ‘©πŸ½β€πŸŒΎ

Topics

Resources

Code of conduct

Security policy

Stars

112 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages