Run locally-installed node module executables.
Clone or download
Latest commit 03d91cb Apr 11, 2018
Failed to load latest commit information.
bin Update dependencies. Remove spawn-sync. Apr 10, 2018
test Options for exec is optional (#13) Mar 17, 2017
.gitignore Initial commit Apr 21, 2014
.travis.yml Test node 8 Apr 9, 2018 Release 5.0.1 Apr 12, 2018
LICENSE Add license Apr 21, 2014 Update Mar 2, 2017
index.js Fix broken package reference. Apr 12, 2018
package.json Release 5.0.1 Apr 12, 2018



Build Status

Run executables in node_modules from the command-line

Use npm-run to ensure you're using the same version of a package on the command-line and in package.json scripts.

Any executable available to an npm lifecycle script is available to npm-run.


> npm install mocha # mocha installed in ./node_modules
> npm-run mocha test/* # uses locally installed mocha executable 
> npm-run --help
Usage: npm-run command [...args]
  --version  Display version & exit.
  --help     Display this help & exit.

Hint: to print augmented path use:
npm-run node -p process.env.PATH


> npm install -g npm-run

Programmatic API

The API of npm-run basically wraps core child_process methods (exec, spawn, etc) such that locally install package executables will be on the PATH when the command runs.

npmRun(command[, options], callback)

Alias of npmRun.exec.

npmRun.exec(command[, options], callback)

Takes same arguments as node's exec.

npmRun.exec('mocha --debug-brk --sort', {cwd: __dirname + '/tests'}, function (err, stdout, stderr) {
  // err Error or null if there was no error
  // stdout Buffer|String
  // stderr Buffer|String

npmRun.sync(command[, options])

Alias of npmRun.execSync

npmRun.execSync(command[, options])

Takes same arguments as node's execSync.

var stdout = npmRun.execSync(
  'mocha --debug-brk --sort',
  {cwd: __dirname + '/tests'}
stdout // command output as Buffer|String

npmRun.spawnSync(command[, args][, options])

Takes same arguments as node's spawnSync.

var child = npmRun.spawnSync(
  '--debug-brk --sort'.split(' '),
  {cwd: __dirname + '/tests'}
child.stdout // stdout Buffer|String
child.stderr // stderr Buffer|String
child.status // exit code

npmRun.spawn(command[, args][, options])

Takes same arguments as node's spawn.

var child = npmRun.spawn(
  '--debug-brk --sort'.split(' '),
  {cwd: __dirname + '/tests'}
child.stdout // stdout Stream
child.stderr // stderr Stream
child.on('exit', function (code) {
  code // exit code


Due to npm's install algorithm node_modules/.bin is not guaranteed to contain your executable. npm-run uses the same mechanism npm uses to locate the correct executable.

See Also