Setup

Install

Add Pastoralist as a dev dependency:

npm install pastoralist --save-dev

Other package managers work too:

pnpm add pastoralist --save-dev
yarn add pastoralist --dev
bun add pastoralist --dev

Initialize

Run a read-only setup and override health check first:

npx pastoralist doctor

doctor runs in dry-run summary mode, so it shows current override health without modifying package.json.

Print the full first-run checklist when you want local setup, agent setup, and CI setup in one place:

npx pastoralist onboard

Install the Pastoralist agent skill in a repo:

npx pastoralist --init agent-skill

Set up local dev with selected skills and hooks:

npx -p pastoralist pastoralist-setup-local-dev --skills all --hooks git,postinstall

Run the guided setup:

npx pastoralist init

The initializer can detect workspace packages, ask whether security checks should run, and save the configuration in package.json or a config file.

For a simple project, you can also run Pastoralist directly:

npx pastoralist

It will scan your package manager overrides or resolutions, update the pastoralist.appendix, and leave unrelated package fields alone.

Add The Install Hook

Most projects should run Pastoralist after dependency installs:

{
  "scripts": {
    "postinstall": "pastoralist"
  }
}

Pastoralist can add that hook automatically:

npx pastoralist --setup-hook

Verify Changes

Preview the package.json update before writing anything:

npx pastoralist --dry-run

Print summary metrics for CI or release checks:

npx pastoralist --summary

Remove overrides that no package still depends on:

npx pastoralist --remove-unused

Common Starting Config

For a workspace project with OSV security checks:

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

Next, read Configuration for all options or Workspaces & Monorepos for monorepo setup.