Why does npm exec say a published CLI is not recognized inside its own source tree?

[b-hash88]

Reproduced on Windows 11 with Node 24.15.0 and npm 11.12.1.

Symptom

'<command>' is not recognized as an internal or external command,
operable program or batch file.

The surprising case was this release check:

npm exec --yes --package=<name>@<version> -- <command> --help

Run from a package source root whose local name and version exactly matched the requested package, it exited 1 with the error above. The identical command run from a neutral consumer directory exited 0 and executed the published registry package.

Cause

npm exec can treat the exact local package name/version as satisfying --package. The source tree has a bin declaration, but it does not necessarily have an installed node_modules/.bin shim on PATH, so npm does not fetch the registry copy and Windows cannot resolve the command. In a neutral directory there is no matching local package, so npm installs the requested version into its cache and exposes the executable on PATH.

Release check

npm view <name>@<version> dist.integrity
cd <neutral-directory-outside-the-package-source-tree>
npm exec --yes --package=<name>@<version> -- <command> --help

A direct local node invocation proves the source entry point works. The neutral npm exec proves the published artifact can be fetched and linked. They test different things; a global install hides that distinction.

The complete guide is free: https://b-hash88.github.io/knownfix/fixes/npm-exec-local-bin-not-found.html

Official npm documentation: https://docs.npmjs.com/cli/v11/commands/npm-exec