npm-pkg-settings

name: npm-pkg-settings description: Manages npm package publish settings — listing packages, viewing/updating access controls, linking trusted publishers, adding maintainers, and generating OTP codes. Use when automating npm package configuration, setting up trusted publishers for provenance, managing 2FA publishing access, or bulk-updating npm packages.

npm-pkg-settings

CLI and programmatic API for managing npm package publish settings. Works by automating the npm website, since npm has no public API for package settings. Automatically handles OTP generation and submission during all operations.

Setup

Environment variables

Set in .env (auto-loaded by CLI) or export in shell:

Getting the OTP secret

Extract from npm's 2FA setup QR code:

# From a QR code screenshot
npm-pkg-settings decode-secret ./qr-code.png

# From an otpauth-migration:// URL (e.g. from Google Authenticator export)
npm-pkg-settings decode-secret 'otpauth-migration://offline?data=...'

Session and gitignore

The CLI persists cookies to .npm-pkg-settings.cookies.json. Add to .gitignore:

.npm-pkg-settings.cookies.json
.env

If a session expires, the tool re-authenticates automatically (requires NPM_USERNAME and NPM_PASSWORD).

CLI

update flags

All flags can be combined in a single call. Changes are previewed before applying (skip with --yes).

GitHub trusted publishers are validated (repo existence, workflow file) before applying.

Common workflows

Bulk-update all packages (trusted publisher + strict 2FA)

# Get package names as JSON array, then loop
npm-pkg-settings list --json | jq -r '.[].name' | while read -r pkg; do
  npm-pkg-settings update "$pkg" \
    --trusted-publisher "github:owner/repo?workflow=release.yml" \
    --publishing-access strict \
    --yes
done

Audit packages missing trusted publishers

# List all packages, then check each
for pkg in $(npm-pkg-settings list --json | jq -r '.[].name'); do
  settings=$(npm-pkg-settings view "$pkg" 2>&1)
  if ! echo "$settings" | grep -q "Trusted publishers"; then
    echo "MISSING: $pkg"
  fi
done

Generate OTP for manual npm operations

npm-pkg-settings otp
# Output: 123456
#         expires in 18s

Programmatic API

import { createClient } from 'npm-pkg-settings'

const client = createClient({
  otpSecret: process.env.NPM_OTP_SECRET!,
  username: process.env.NPM_USERNAME,      // optional — enables login()
  password: process.env.NPM_PASSWORD,      // optional — enables login()
  sessionFile: '.npm-pkg-settings.cookies.json', // optional, this is the default
})

Client methods

Bulk update example (programmatic)

const client = createClient({ otpSecret: process.env.NPM_OTP_SECRET! })
await client.login()

const packages = await client.listPackages()
for (const { name } of packages) {
  await client.linkTrustedPublisher(name, {
    type: 'github',
    owner: 'my-org',
    repository: name,
    workflow: 'release.yml',
  })
  await client.setPublishingAccess(name, 'tfa-always-required')
}

Publishing access values

Key types