Research npm packages by metadata, downloads, maintainers, freshness, and dependency risk.
Quick Start
1. Install
See Install above.
2. Credentials
No credentials are required for public npm registry reads.
3. Verify Setup
npm-pp-cli doctor
This checks your configuration and npm registry connectivity.
4. Try Your First Command
npm-pp-cli package react --json
Usage
Run npm-pp-cli --help for the full command reference and flag list.
Commands
intelligence
npm-pp-cli package <name> - Summarize one package with latest version, maintainers, dependencies, publish freshness, and last-month downloads.npm-pp-cli compare <package> [package...] - Compare packages by adoption, freshness, maintainers, and dependency surface.npm-pp-cli risk <package> - Score maintenance and adoption risk with explicit signals.
downloads
Manage downloads
npm-pp-cli downloads get - Gets the downloads per day for a given period for all packages.npm-pp-cli downloads get-point - Gets the downloads per day for a given period for a specific package.npm-pp-cli downloads get-range - Gets the downloads per day for a given period for all packages.npm-pp-cli downloads get-range-2 - Gets the downloads per day for a given period for a specific package.
versions
Manage versions
Output Formats
# Human-readable table (default in terminal, JSON when piped)
npm-pp-cli compare react vue svelte
# JSON for scripting and agents
npm-pp-cli package react --json
# Filter to specific fields
npm-pp-cli compare express fastify koa --json --select name,latest_version,last_month_downloads
# Dry run — show the request without sending
npm-pp-cli package react --dry-run
# Agent mode — JSON + compact + no prompts in one flag
npm-pp-cli downloads get mock-value --agent
Agent Usage
This CLI is designed for AI agent consumption:
- Non-interactive - never prompts, every input is a flag
- Pipeable -
--json output to stdout, errors to stderr
- Filterable -
--select id,name returns only fields you need
- Previewable -
--dry-run shows the request without sending
- Read-only by default - this CLI does not create, update, delete, publish, send, or mutate remote resources
- Offline-friendly - sync/search commands can use the local SQLite store when available
- Agent-safe by default - no colors or formatting unless
--human-friendly is set
Exit codes: 0 success, 2 usage error, 3 not found, 4 auth error, 5 API error, 7 rate limited, 10 config error.
Health Check
npm-pp-cli doctor
Verifies configuration and connectivity to the npm registry.
Configuration
Config file: ~/.config/npm-pp-cli/config.toml
Static request headers can be configured under headers; per-command header overrides take precedence.
Environment variables:
| Name | Kind | Required | Description |
|---|
NPM_BASE_URL | override | No | Point commands at a mock or alternate npm-compatible registry. |
Troubleshooting
Not found errors (exit code 3)
- Check the package name is correct.
- Scoped packages can be passed in normal form, for example
@types/node.
HTTP Transport
This CLI uses Chrome-compatible HTTP transport for browser-facing endpoints. It does not require a resident browser process for normal API calls.
Generated by CLI Printing Press