Wondering what’s next for npm?Check out our public roadmap! »


1.2.1 • Public • Published


Tiny wrapper around child_process.spawn() / exec() which provides some additional functionality.

Differences from spawn / exec:

  • Always returns a promise for running processes. That promise can return output if buffer is enabled
  • Can easily prefix output to STDOUT / STDERR or both
  • Can accept a single array of command arguments rather than treating the program + args separately
  • Can accept a single string command which is correctly transformed internally
  • Optionally can buffer and provide all output when resolving / rejecting
  • Supports piping
  • Auto-trimming out output
  • Hashbangs supported
  • Can natively accept JSON and fail if not given valid input
var exec = require('@momsfriendlydevco/exec');
exec('echo "Hello world"')
    .then(()=> /* ... */)
exec(['docker', 'build', '--tag=momsfriendlydevco/test', '.'], {
    prefix: '[docker]',
    .then(()=> /* ... */)


This module uses the Debug NPM package and responds to exec.

To see verbose debugging output simply set DEBUG=exec or any valid glob expression.

> DEBUG=exec node someNodeFile.js


This module exposes a function (which returns a promise) as well as a few utility functions. The function takes an array (or string) of arguments where the executable is the first item within that array. An additional options object can be passed.

exec([cmd], <cmd+args|args>, [options])

Supported options:

Option Type Default Description
buffer boolean undefined Set both bufferStdout + bufferStderr at once
bufferStdout boolean false When resolving the promise provide the output from the command as the value of the resolved promise
bufferStderr boolean false As with bufferStdout but also include STDERR stream data
log boolean or function undefined Set both logStdout + logStderr at once
logStdout boolean or function console.log Logging function to use when outputting STDOUT, set to falsy to disable
logStderr boolean or function console.log Similar to logStdout but with the STDERR stream
prefix string or function undefined Sets both prefixStdout + prefixStderr at once
prefixStdout string or function undefined Sets a string prefix for any STDOUT output, if a function it is called as (msg) and uses the return value, effectively acting as a wrapper
prefixStderr string or function undefined Similar functionality to prefixStdout but with STDERR streams
rejectError string 'Non-zero exit code' String to reject with if the exit code is not present in resolveCodes
reformat boolean undefined Set both reformatStdout + reformatStderr at once
reformatStdout boolean false When accepting data from Stdout and prefixStdout is enabled, also split newline input so each newline is prefixed
reformatStderr boolean false As with reformatStdout but also reformat STDERR stream data
resolveCodes array [0] Array of numeric error codes to accept as a valid response
json boolean false Attempt to convert the contents of the output buffer (contents dictated by buffer* into JSON before returning
pipe boolean or string 'auto' Use the shell to execute, if 'auto' pipes are detected automatically
shell string '/bin/sh' A STDIN processing shell, used when pipe is true or auto detected
hashbang boolean true If specified the file is opened and hashbangReadLength bytes examined for a hashbang, if one is found the command is prefixed with it
hashbangReadLength number 100 How many bytes to explore at the start of files for the hashbang
trim boolean true Automatically trim output to remove trailing newlines and spaces
trimRegExp RegExp /[\n\s]+$/m The regular expression used when trimming
env object {} Environment variables to pass to the shell
cwd string undeinfed The current working directory to execute the process within
uid number undefined The UID who owns the process
gid number undefined The GID who owns the process


  • Setting log or log{Stdout,Stderr} automatically implies the respective logStdout / logStderr function to be true


An object containing the default options for exec() which can be globally changed.


Take a command line and split it into a child_process.spawn() compatible array.


Take a disected child_process.spawn() comaptible array and convert it into a single line, runnable shell command.


npm i @momsfriendlydevco/[email protected]





Unpacked Size

17.3 kB

Total Files


Last publish


  • avatar
  • avatar
  • avatar
  • avatar
  • avatar