Skip to content
pkgPlease Docs

Getting Started

pkgPlease sits in front of npm as a registry proxy: every install goes through https://npm.pkgpls.com instead of https://registry.npmjs.org directly, so pkgPlease can score packages and enforce your org’s policy before a tarball reaches disk.

The dashboard (https://app.pkgplease.com) and the registry proxy (https://npm.pkgpls.com) are deliberately on separate domains — the dashboard’s WAF and bot protection would otherwise interfere with npm/pnpm’s non-browser requests.

1. Issue a token

Section titled “1. Issue a token”

Go to Settings → Service Tokens and issue a new token with scope “Registry only” (the recommended default — it can install packages but not call the management API). Copy the token; it’s shown once.

See Registry & Tokens for the other token types (developer, agent, provisioner) and when to use each.

Setting up coding agents rather than a human or CI workflow? Skip to Agent Setup (MCP Server) — the MCP server provisions its own short-lived tokens and writes .npmrc for you, so none of the manual steps below apply.

2. Configure your npm client

Section titled “2. Configure your npm client”

Add these two lines to your .npmrc (project-level or ~/.npmrc):

registry=https://npm.pkgpls.com/
//npm.pkgpls.com/:_authToken=${PKGPLEASE_NPM_TOKEN}

Set PKGPLEASE_NPM_TOKEN (any name works — this is just an example) as an environment variable rather than writing the raw token into the file — npm expands ${VAR} syntax in .npmrc at install time, so the token never touches a file that might get committed. This is a separate credential from the agent CLI’s PKGPLEASE_PRV_TOKEN — see Agent Setup if you’re setting up a coding agent rather than your own npm client.

pnpm does not expand ${VAR} syntax from a project-level .npmrc — put this in your user-level ~/.npmrc instead if you use pnpm, or substitute the literal token.

3. Restricted-network CI

Section titled “3. Restricted-network CI”

If your CI runner has an egress allowlist, add npm.pkgpls.com to it — installs will otherwise fail to resolve the registry host.

Next steps

Section titled “Next steps”