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.
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.
Install the global CLI with npm or Homebrew:
npm install --global pastoralist
# or
brew install yowainwright/tap/pastoralistFor a project, install it as a dev dependency:
npm install pastoralist --save-dev
npx pastoralist doctor
npx pastoralistdoctor 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.
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.
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.
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-runType:
boolean options
Prints CLI help or the installed package version.
pastoralist --help
pastoralist --version # -vCheck the installed version and available commands before adding Pastoralist to scripts or CI.
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 --styleguideType:
command
Runs a read-only health check. Internally this enables dryRun: true and
summary: true.
pastoralist doctor
pastoralist doctor --outputFormat jsonType:
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 initType:
command
Installs the bundled Pastoralist agent skill into
.agents/skills/pastoralist. Existing unmanaged skill files are preserved.
pastoralist init agent-skillType:
string optionDefault:"package.json"
Selects the package manifest Pastoralist should read and update.
pastoralist --path packages/app/package.json # -p packages/app/package.jsonType:
string option
Sets the root directory used to resolve relative paths, config files, lockfiles, patches, and workspace globs.
pastoralist --root ../my-project # -r ../my-projectType:
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"Type:
string[] option
Excludes package manifests from --depPaths matching.
pastoralist --ignore "**/node_modules/**"Type:
boolean option
Enables debug logging for CLI execution.
pastoralist --debugType:
boolean option
Previews changes to project files. Security providers may still write caches.
pastoralist --dry-runType:
"text" | "json" optionDefault:"text"
Selects terminal output or a single machine-readable JSON result.
pastoralist --dry-run --outputFormat jsonJSON output includes result status, findings, applied overrides, and metrics.
{
"success": true,
"updated": false,
"overrideCount": 1
}Type:
boolean option
Prints the metrics table after a text-mode run.
pastoralist --summaryType:
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 --checkSecurityType:
boolean option
Adds pastoralist to the target manifest's postinstall script. Existing
postinstall scripts are appended with && pastoralist.
pastoralist --setup-hookKeeps the appendix current after package installs:
{
"scripts": {
- "postinstall": "build"
+ "postinstall": "build && pastoralist"
}
}Type:
boolean option
Removes verified unused override entries from the active override source and
appendix. Preview first with --dry-run.
pastoralist --remove-unusedType:
boolean option
Runs vulnerability scanning before the appendix update. Fixable security findings can add override data and security ledger fields.
pastoralist --checkSecurityApply fixes with --interactive or --forceSecurityRefactor.
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 osvType:
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"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 --promptForReasonsDirect 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.
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-cacheUse these to avoid repeated provider calls, shorten cache windows, or force a fresh advisory lookup.
Shout out to Mardin for the conversation, insight, and pairing around this topic.
Made by @yowainwright. MIT, 2022-2026.