npm/cli
github.com/npm/cli ↗ · 3955 files · 130.8 MB · scan capped
docs Scripts to build the npm docs.
Overview
At commit b317f16c80df02ea3628cfa77170d5ae9b59720c, this repository implements npm 12.2.0, a Node.js command-line package manager for JavaScript developers and package publishers. It combines dependency graph resolution, reproducible installation, package execution, registry administration, and publishing through npm and npx entrypoints. Distinctive capabilities in this source include install-script approvals, release-age restrictions, local dependency patches, root-owned manifest transformations, and staged publishing.
System map
The runtime is a Node.js CLI with a central Npm object coordinating configuration, command dispatch, output, and error handling. Independently packaged workspaces provide dependency-tree management and registry operations. Persistent state spans project manifests and locks, installed modules, caches, logs, and user configuration. Distribution bundles runtime dependencies and builds documentation during packaging.
- package.json exposes npm through bin/npm-cli.js and npx through bin/npx-cli.js; index.js invokes the CLI when executed directly and rejects imports with the removed-programmatic-API error.
- lib/cli.js optionally enables Node's compile cache, then validateEngines installs early syntax-error handlers before loading the asynchronous CLI entry module.
- Npm constructs Config and Display alongside LogFile and Timers; Npm.cmd resolves registered names before dynamically requiring a command implementation.
- execCommandClass handles recursive subcommands, help, workspace support, developer-engine checks, and separate execution branches for commands with definitions versus legacy commands.
- Config stores default, builtin, global, user, project, environment, and CLI layers in a prototype chain; flat options are generated from lower to higher priority.
- Arborist owns actual, virtual, and ideal dependency trees and composes tracker, resolution, loading, rebuilding, reification, and isolated-install behavior through mixins.
- Installation delegates to Arborist and pacote; publishing delegates to libnpmpack, libnpmpublish, npm-registry-fetch, and optional CI OIDC exchange.
- The distributable includes bin, lib, documentation, and man pages with bundled runtime dependencies; prepack builds docs, test invokes TAP, lint invokes ESLint, and supported Node versions are explicitly constrained.
Feature catalog
The command registry spans dependency maintenance, package inspection, script execution, registry administration, publishing, and developer assistance. Commands support aliases and abbreviations, with workspace behavior determined by command metadata. Specialized surfaces manage script approvals, patches, trusted publishing, and staged release approval. The catalog below groups registered commands; detailed implementation inspection concentrated on installation, execution, authentication, auditing, and publishing.
- Dependency maintenance commands include install, ci, update, uninstall, dedupe, find-dupes, prune, rebuild, and link; install supports global mode, workspace selection, package-lock-only, platform filters, and source restrictions.
- Inspection and discovery commands include ls, ll, explain, query, outdated, diff, sbom, fund, search, and view; audit implements advisory reporting, fix, and installed-package signature verification.
- Execution and project workflows include run, exec, start, stop, restart, test, install-test, install-ci-test, init, edit, and explore; npx maps to exec, and run supports script listing plus workspace execution.
- Release commands include pack, publish, unpublish, version, dist-tag, deprecate, and undeprecate; stage exposes publish, list, view, approve, reject, and download with deferred proof-of-presence.
- Account and registry administration commands include access, org, owner, team, profile, token, login, logout, and whoami; trust provides GitHub, GitLab, CircleCI, list, and revoke subcommands.
- Configuration and local diagnostics are registered as config, get, set, pkg, cache, doctor, ping, prefix, and root; command validation rejects unknown CLI options while unknown file settings warn unless strict-npmrc is enabled.
- Help and navigation commands include help, help-search, docs, bugs, repo, and completion; command classes generate usage from descriptions, aliases, parameters, definitions, and subcommand tables.
- Policy and repair features include install-scripts approve/deny/ls/prune, approve-scripts and deny-scripts, patch add/commit/update/ls/rm, and min-release-age filtering with exemptions and blocked-audit-fix reporting.
Data flow
CLI arguments, environment settings, and configuration files become typed configuration and flattened options consumed by command implementations. Installation turns requested specs and manifest metadata into an ideal graph, then reconciles that graph with disk. Authentication produces registry-scoped configuration, while publishing produces tarball bytes and registry requests. Output is routed through proc-log and finalized centrally.
- npx rewrites process.argv to npm exec, translates -p, --shell, and --no-install, removes obsolete options, and inserts -- before the first positional argument before invoking cli(process).
- Config.load loads defaults and builtin configuration, parses CLI and npm_config_* environment values, then discovers project, user, and global files before exporting child-process settings.
- Npm.#load takes positional arguments from parsedArgv.remain, removes the command token, resolves aliases, initializes display settings, and returns the raw command spelling plus remaining arguments.
- Install combines flatOptions, destination path, requested additions, workspace names, and resolved script policy into Arborist options; buildIdealTree initializes state, applies extensions and requests, resolves dependencies, checks platform compatibility, and resolves patches.
- Reification passes each non-link node's resolved source and integrity to pacote.extract, determines root source-policy eligibility from dependency edges, then applies its patch; link nodes instead enter a filesystem symlink path.
- Successful installation persistence updates dependency fields through PackageJson.save, saves ideal-tree lock metadata, then transfers idealTree to actualTree and writes node_modules/.package-lock.json or a linked-layout hidden lock.
- Login selects a registry, obtains a token through auth.login, stores it under a registry-scoped user configuration key, and serializes raw INI data to the configured user file with mode 0600.
- Publishing transforms a package spec into a prepared manifest and in-memory tarball, rereads publication settings, selects registry credentials, and sends bytes through libpub; Npm.finish flushes buffered output with final JSON/error metadata.
Behavior traces
The investigated flows include startup and dispatch, installation through filesystem persistence, clean installation, login through credential persistence, explicit script execution, and publishing. Each trace follows source call order and preserves significant branches. Installation and ci differ in validation, cleanup, and root-script timing. These are static traces rather than observed runtime executions.
- Startup: npm-cli.js → cli(process) → validateEngines → getCli() → entry(process, validation) → gracefulify(fs) → new ExitHandler → new Npm → npm.load(); unsupported but parseable Node versions receive a warning.
- Dispatch: entry awaits load, exits early for version-only mode or missing commands, starts npm.exec(command,args), launches an unawaited update notification, awaits execution, and routes success or failure to exitHandler.exit.
- Bare local install: Install.exec → resolveAllowScripts → root preinstall when scripts are enabled → new Arborist → strictAllowScriptsPreflight → arb.reify → install/postinstall/prepublish/preprepare/prepare/postprepare → reifyFinish; explicit additions and global installs skip this root lifecycle sequence.
- Arborist persistence: reify → _loadTrees → _diffTrees → #reifyPackages → _saveIdealTree → actualize tree → save hidden lock; local tree loading runs loadActual and buildIdealTree concurrently, while global loading builds ideal state first.
- Clean install: CI.exec rejects global mode and CLI patch-relax flags → loadVirtual on one Arborist → buildIdealTree on another → script preflight → validate inventories, packageExtensions, and extension hash → clear workspace node_modules unless dry-run → root preinstall → reify → remaining root hooks → reifyFinish.
- Login persistence: Login.exec chooses scoped registry unless CLI overrides it → getCredentialsByURI → auth.login → loginWeb or ENYI fallback to username/password and loginCouch through otplease → setCredentialsByURI → save('user') → print message.
- Explicit script: RunScript.exec → #run → normalize package → resolve requested/default event → handle missing script or if-present → construct pre/main/post events → await runScript for each; only the main event receives forwarded positional arguments.
- Publish: exec → #publish → #getManifest → reject non-private packageExtensions → directory prepublishOnly → pack → reread manifest → pickRegistry → oidc → credential/version checks → libpub through otplease, or staged libpub without OTP → directory publish/postpublish hooks → output.
Testing signals
Tests and CI were inspected, not executed; test existence and configured coverage thresholds are not passing results. The inspected manifests and tests use TAP, correcting the inventory's Vitest tag for these surfaces. Coverage combines temporary-project integration tests, mocked registries and scripts, output assertions, and smoke tests. Inventory and test inspection were bounded, with explicit platform and live-integration limits.
- Root tests use tap ^16.3.9 and the test script is tap; docs and mock-globals also use TAP. CONTRIBUTING expects regression tests and describes a 100% coverage requirement, without establishing achieved coverage.
- Root TAP excludes docs, smoke-tests, mock-globals, mock-registry, and workspaces from root coverage/test discovery; workspace suites therefore require separate execution rather than relying on root tests.
- mock-npm breaks configuration-definition singleton caching, subclasses Npm, awaits background log cleanup, and reconstructs config.argv for direct exec calls; these deliberate test/runtime differences matter when reproducing dispatch bugs.
- CLI entry tests assert process-title sanitization and redaction of registry URL passwords in both separate-value and equals-style arguments; these assertions cover specified examples rather than arbitrary secrets.
- Install regression tests check preinstall before dependency presence, postinstall afterward, ignore-scripts suppression, and preinstall failure preventing dependency installation; the script runner is mocked rather than executing a real bootstrap command.
- ci tests inspect real temporary node_modules changes with mocked tarball/advisory responses, verify dry-run preservation and repeated cleanup, reject stale packageExtensions state, and assert lifecycle ordering and failure behavior.
- Login tests use mock globals and MockRegistry, then inspect persisted INI state for token replacement, preserved scoped email, and scoped registry selection; they do not demonstrate successful authentication against a live registry.
- CI configures Linux, macOS, and Windows tests across Node 22/24/26, with Intel macOS combinations excluded; smoke/publish-dryrun jobs run on Linux, and the exec smoke case explicitly skips Windows. These workflow definitions were inspected, not run.
Risk map
These findings describe source-level trust boundaries and behavioral hazards, not confirmed vulnerabilities. Installation can execute project code, mutate configured filesystem locations, and consume registry metadata with credentials. Configuration and script-policy behavior have branches that comments alone do not fully explain. Mocked tests and unexecuted CI leave runtime and live-provider behavior unverified.
- NpmExtension.load imports or requires project-selected code in-process; cloning manifests and restricting returned fields constrain transformation results but do not sandbox module-level execution.
- Hypothesis requiring validation: discover checks extension-file containment using resolved path strings, then reads/imports that path; a symlink's real target may escape that lexical root boundary. This inspection does not establish exploitability. (inferred)
- Bare install runs root preinstall before strictAllowScriptsPreflight; strict dependency-script checks therefore do not precede all root-owned code execution.
- ci clears node_modules before root preinstall, so a failing bootstrap script can leave existing installations removed; dry-run guards cleanup but does not guard the root lifecycle calls.
- Exec says its policy should consult user/global npmrc only, but resolveAllowScripts still probes project/user/global/builtin sources when skipProjectConfig is true; that flag skips package.json rather than the project npmrc source.
- User credentials are serialized into a configured file, with passwords base64-encoded rather than encrypted and chmod applied after writing; Npm also creates configured caches/log directories and labels argv redaction best-effort.
- Publish dry-run suppresses libpub but still reaches directory lifecycle hooks, OIDC setup, and registry version checks; #registryVersions catches any fetch/parsing error and returns an empty version set.
- Reify has staged rollback for retirement, sparse-tree creation, unpacking, and builds, but explicitly performs final trash removal without rollback; linked installs also temporarily swap tree representations and restore them in finally.
Extension points
Extension mechanisms range from internal command registration to project-controlled dependency policy. Command metadata integrates help, parsing, workspace behavior, and nested routing. Arborist mixes independently defined behaviors and supports both declarative and executable manifest repair. These extension points carry different trust and persistence contracts.
- A top-level command plugs into the alphabetically sorted commands table and corresponding lib/commands filename; aliases and abbreviations pass through deref before Npm.cmd loads the class.
- BaseCommand metadata provides name, description, params, definitions, subcommands, and positional limits; flags builds types/defaults/aliases from definitions and validates before returning parsed flags and positional arguments.
- Nested command families register classes through static subcommands objects, as stage and trust demonstrate; execCommandClass recursively removes consumed command names and adjusts flag-parser depth.
- Global configuration extensions belong in definitions.js as Definition instances; definitions/index.js derives shorthand/default tables and invokes per-definition flatten handlers while preserving registry-scoped settings.
- Arborist behavior is composed through a mixins array reduced over EventEmitter, providing a direct internal integration point for tree loading, resolution, rebuilding, and installation strategies.
- Root packageExtensions rules match package names and semver ranges and may change only dependency/peer fields; normal dependencies are add-only, while peer ranges and peer metadata can be repaired.
- Root .npm-extension.mjs/.cjs exports transformManifest(pkg,context); NpmExtension hashes the selected file, requires synchronous object results, memoizes by package identity, and returns cloned manifests with provenance.
- Dependency patches integrate through patchedDependencies resolution during buildIdealTree and application immediately after extraction; patch commands provide edit/commit/update workflows and reject non-registry target specs.
Contributor handoff
Begin with the CLI coordinator, owning command, configuration definitions, and relevant workspace before changing behavior. Preserve source precedence, workspace boundaries, lifecycle ordering, and lockfile contracts. Tests and CI were inspected, not executed, and this inventory is bounded rather than exhaustive. Proposed checks below are handoff guidance for an execution-authorized task.
- Read package.json and CONTRIBUTING first; use node . <command> to invoke the checkout in an authorized development task, since index.js rejects programmatic import and installed npm may refer to another version.
- For dispatch changes, read cmd-list.js, Npm.execCommandClass, and BaseCommand together; preserve aliases, nested command depth, help generation, legacy execution, and workspace capability checks.
- Keep compatibility-sensitive bootstrap files within the ES6 syntax and restricted-require rules in .eslintrc.local.js; npx currently has a documented exception because it imports the configuration definition graph.
- For configuration edits, check source precedence and flattening, plus validateCli's deferred validation; repair-oriented commands can bypass validation, and environment unknowns intentionally warn rather than error.
- For installation changes, preserve actual/virtual/ideal ownership and save semantics: ci forces save:false and ignoreExtension:true while validating extension hashes; update can still save lockfiles despite save:false.
- Use existing mock-npm fixtures for command regression tests and explicitly account for reconstructed argv and awaited log cleanup; maintain install/ci tests that distinguish preinstall timing, script suppression, and bootstrap failure.
- Tests and CI were inspected, not executed. When authorized, start with node . run test -- <relevant-test-file>, then the affected workspace suite and lint; root test-all and lint-all scripts exist, and root coverage excludes workspaces.
- Keep edits focused on owning source, tests, and documentation: package.json is partially template-oss-managed, CI declares generated ownership, and CONTRIBUTING reserves dependency updates and tooling/automation maintenance for the core team.
Languages
| Language | Files | Share of source |
|---|---|---|
| JSON | 3913 | docs/config |
| JavaScript | 1639 | 96% |
| Markdown | 262 | docs/config |
| Python | 58 | 3% |
| YAML | 33 | docs/config |
| Shell | 5 | 0% |
| C++ | 2 | 0% |
| C# | 1 | 0% |
Start reading here
Probable source entrypoint: index.js — inferred from the directory tree and manifest, not the upstream docs.
Source roots
lib/ (137 files)
Source layout — lib/
| Path | Files |
|---|---|
lib/cli/ | 4 |
lib/commands/ | 79 |
lib/utils/ | 47 |
lib/arborist-cmd.js | 1 |
lib/base-cmd.js | 1 |
lib/cli.js | 1 |
lib/lifecycle-cmd.js | 1 |
lib/npm.js | 1 |
lib/package-url-cmd.js | 1 |
lib/trust-cmd.js | 1 |
Repository structure
| Top-level path | Files |
|---|---|
workspaces/ | 3420 |
test/ | 141 |
lib/ | 137 |
docs/ | 100 |
tap-snapshots/ | 40 |
.github/ | 34 |
scripts/ | 29 |
smoke-tests/ | 13 |
Docs found: CONTRIBUTING.mddocs/README.mddocs/lib/content/commands/npm-access.mddocs/lib/content/commands/npm-approve-scripts.mddocs/lib/content/commands/npm-audit.mddocs/lib/content/commands/npm-bugs.mddocs/lib/content/commands/npm-cache.mddocs/lib/content/commands/npm-ci.mddocs/lib/content/commands/npm-completion.mddocs/lib/content/commands/npm-config.md
Package
package.json — npm v12.2.0, 80 declared dependencies.
@isaacs/string-locale-compare@npmcli/arborist@npmcli/config@npmcli/docs@npmcli/eslint-config@npmcli/fs@npmcli/git@npmcli/installed-package-contents@npmcli/map-workspaces@npmcli/metavuln-calculator@npmcli/mock-globals@npmcli/mock-registry
CI & config entrypoints
.github/workflows/audit.yml— GitHub Actions workflow.github/workflows/backport.yml— GitHub Actions workflow.github/workflows/ci-libnpmaccess.yml— GitHub Actions workflow.github/workflows/ci-libnpmdiff.yml— GitHub Actions workflow.github/workflows/ci-libnpmexec.yml— GitHub Actions workflow.github/workflows/ci-libnpmfund.yml— GitHub Actions workflow.github/workflows/ci-libnpmorg.yml— GitHub Actions workflow.github/workflows/ci-libnpmpack.yml— GitHub Actions workflow.github/workflows/ci-libnpmpublish.yml— GitHub Actions workflow.github/workflows/ci-libnpmsearch.yml— GitHub Actions workflow
Structural health signals
Average score 6.1/10 across 96 analyzed source files; 60 hotspots surfaced.
workspaces/arborist/lib/node.js— 1576 lines, score 4 (Large file, Deep nesting)workspaces/arborist/lib/query-selector-all.js— 961 lines, score 4 (Large file, Deep nesting)test/lib/commands/install.js— 1310 lines, score 4.5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
b317f16c80df2026-10-02 — fix: write registry allowScripts keys under install-strategy=linked (#9941)c276cadf785c2026-09-30 — chore: release 12.2.09741b645b0112026-09-30 — feat(dist-tag): support OIDC authentication (#10038)0c3b82a9a6122026-09-24 — docs: update npm stage docs to reflect that it can create new packages (#10017)e1581be901192026-09-24 — chore(config): isolate tests from host npmrc files (#10015)