1. module execa
   1. function execa (cmd, args, opts)
   2. function execa.errname (uv, code)
   3. function execa.index (cmd, args, opts)
   4. function execa.shell (cmd, opts)
   5. function execa.shellSync (cmd, opts)
   6. function execa.spawn ()
   7. function execa.stderr ()
   8. function execa.stdout ()
   9. function execa.sync (cmd, args, opts)
2. module execa.errname
   1. function execa.errname (uv, code)
   2. function execa.errname.__test__ (uv, code)
3. module execa.index
   1. function execa.index (cmd, args, opts)
   2. function execa.index.shell (cmd, opts)
   3. function execa.index.shellSync (cmd, opts)
   4. function execa.index.spawn ()
   5. function execa.index.stderr ()
   6. function execa.index.stdout ()
   7. function execa.index.sync (cmd, args, opts)

module execa

function execa (cmd, args, opts)

• description and source-code

  (cmd, args, opts) => {
  	let joinedCmd = cmd;
  
  	if (Array.isArray(args) && args.length > 0) {
  		joinedCmd += ' ' + args.join(' ');
  	}
  
  	const parsed = handleArgs(cmd, args, opts);
  	const encoding = parsed.opts.encoding;
  	const maxBuffer = parsed.opts.maxBuffer;
  
  	let spawned;
  	try {
  		spawned = childProcess.spawn(parsed.cmd, parsed.args, parsed.opts);
  	} catch (err) {
  		return Promise.reject(err);
  	}
  
  	let removeExitHandler;
  	if (parsed.opts.cleanup) {
  		removeExitHandler = onExit(() => {
  			spawned.kill();
  		});
  	}
  
  	let timeoutId = null;
  	let timedOut = false;
  
  	const cleanupTimeout = () => {
  		if (timeoutId) {
  			clearTimeout(timeoutId);
  			timeoutId = null;
  		}
  	};
  
  	if (parsed.opts.timeout > 0) {
  		timeoutId = setTimeout(() => {
  			timeoutId = null;
  			timedOut = true;
  			spawned.kill(parsed.killSignal);
  		}, parsed.opts.timeout);
  	}
  
  	const processDone = new Promise(resolve => {
  		spawned.on('exit', (code, signal) => {
  			cleanupTimeout();
  			resolve({code, signal});
  		});
  
  		spawned.on('error', err => {
  			cleanupTimeout();
  			resolve({err});
  		});
  
  		if (spawned.stdin) {
  			spawned.stdin.on('error', err => {
  				cleanupTimeout();
  				resolve({err});
  			});
  		}
  	});
  
  	function destroy() {
  		if (spawned.stdout) {
  			spawned.stdout.destroy();
  		}
  
  		if (spawned.stderr) {
  			spawned.stderr.destroy();
  		}
  	}
  
  	const promise = pFinally(Promise.all([
  		processDone,
  		getStream(spawned, 'stdout', encoding, maxBuffer),
  		getStream(spawned, 'stderr', encoding, maxBuffer)
  	]).then(arr => {
  		const result = arr[0];
  		const stdout = arr[1];
  		const stderr = arr[2];
  
  		let err = result.err;
  		const code = result.code;
  		const signal = result.signal;
  
  		if (removeExitHandler) {
  			removeExitHandler();
  		}
  
  		if (err || code !== 0 || signal !== null) {
  			if (!err) {
  				const output = parsed.opts.stdio === 'inherit' ? '' : `\n${stderr}${stdout}`;
  				err = new Error(`Command failed: ${joinedCmd}${output}`);
  				err.code = code < 0 ? errname(code) : code;
  			}
  
  			// TODO: missing some timeout logic for killed
  			// https://github.com/nodejs/node/blob/master/lib/child_process.js#L203
  			// err.killed = spawned.killed || killed;
  			err.killed = err.killed || spawned.killed;
  
  			err.stdout = stdout;
  			err.stderr = stderr;
  			err.failed = true;
  			err.signal = signal || null;
  			err.cmd = joinedCmd;
  			err.timedOut = timedOut;
  
  			if (!parsed.opts.reject) {
  				return err;
  			}
  
  			throw err;
  		}
  
  		return {
  			stdout: handleOutput(parsed.opts, stdout),
  			stderr: handleOutput(parsed.opts, stderr),
  			code: 0,
  			failed: false,
  			killed: false,
  			signal: null,
  			cmd: joinedCmd,
  			timedOut: false
  		};
  	}), destroy);
  
  	crossSpawn._enoent.hookChildProcess(spawned, parsed.parsed);
  
  	handleInput(spawned, parsed.opts);
  
  	spawned.then = promise.then.bind(promise);
  	spawned.catch = promise.catch.bind(promise);
  
  	return spawned;
  }

• example usage

  n/a

function execa.errname (uv, code)

• description and source-code

  code => errname(uv, code)

• example usage

  ...
  } catch (err) {
  	console.error('execa/lib/errname: unable to establish process.binding(\'uv\')', err);
  	uv = null;
  }
  
  function errname(uv, code) {
  	if (uv) {
  		return uv.errname(code);
  	}
  
  	if (!(code < 0)) {
  		throw new Error('err >= 0');
  	}
  
  	return `Unknown system error ${code}`;
  ...

function execa.index (cmd, args, opts)

• description and source-code

  (cmd, args, opts) => {
  	let joinedCmd = cmd;
  
  	if (Array.isArray(args) && args.length > 0) {
  		joinedCmd += ' ' + args.join(' ');
  	}
  
  	const parsed = handleArgs(cmd, args, opts);
  	const encoding = parsed.opts.encoding;
  	const maxBuffer = parsed.opts.maxBuffer;
  
  	let spawned;
  	try {
  		spawned = childProcess.spawn(parsed.cmd, parsed.args, parsed.opts);
  	} catch (err) {
  		return Promise.reject(err);
  	}
  
  	let removeExitHandler;
  	if (parsed.opts.cleanup) {
  		removeExitHandler = onExit(() => {
  			spawned.kill();
  		});
  	}
  
  	let timeoutId = null;
  	let timedOut = false;
  
  	const cleanupTimeout = () => {
  		if (timeoutId) {
  			clearTimeout(timeoutId);
  			timeoutId = null;
  		}
  	};
  
  	if (parsed.opts.timeout > 0) {
  		timeoutId = setTimeout(() => {
  			timeoutId = null;
  			timedOut = true;
  			spawned.kill(parsed.killSignal);
  		}, parsed.opts.timeout);
  	}
  
  	const processDone = new Promise(resolve => {
  		spawned.on('exit', (code, signal) => {
  			cleanupTimeout();
  			resolve({code, signal});
  		});
  
  		spawned.on('error', err => {
  			cleanupTimeout();
  			resolve({err});
  		});
  
  		if (spawned.stdin) {
  			spawned.stdin.on('error', err => {
  				cleanupTimeout();
  				resolve({err});
  			});
  		}
  	});
  
  	function destroy() {
  		if (spawned.stdout) {
  			spawned.stdout.destroy();
  		}
  
  		if (spawned.stderr) {
  			spawned.stderr.destroy();
  		}
  	}
  
  	const promise = pFinally(Promise.all([
  		processDone,
  		getStream(spawned, 'stdout', encoding, maxBuffer),
  		getStream(spawned, 'stderr', encoding, maxBuffer)
  	]).then(arr => {
  		const result = arr[0];
  		const stdout = arr[1];
  		const stderr = arr[2];
  
  		let err = result.err;
  		const code = result.code;
  		const signal = result.signal;
  
  		if (removeExitHandler) {
  			removeExitHandler();
  		}
  
  		if (err || code !== 0 || signal !== null) {
  			if (!err) {
  				const output = parsed.opts.stdio === 'inherit' ? '' : `\n${stderr}${stdout}`;
  				err = new Error(`Command failed: ${joinedCmd}${output}`);
  				err.code = code < 0 ? errname(code) : code;
  			}
  
  			// TODO: missing some timeout logic for killed
  			// https://github.com/nodejs/node/blob/master/lib/child_process.js#L203
  			// err.killed = spawned.killed || killed;
  			err.killed = err.killed || spawned.killed;
  
  			err.stdout = stdout;
  			err.stderr = stderr;
  			err.failed = true;
  			err.signal = signal || null;
  			err.cmd = joinedCmd;
  			err.timedOut = timedOut;
  
  			if (!parsed.opts.reject) {
  				return err;
  			}
  
  			throw err;
  		}
  
  		return {
  			stdout: handleOutput(parsed.opts, stdout),
  			stderr: handleOutput(parsed.opts, stderr),
  			code: 0,
  			failed: false,
  			killed: false,
  			signal: null,
  			cmd: joinedCmd,
  			timedOut: false
  		};
  	}), destroy);
  
  	crossSpawn._enoent.hookChildProcess(spawned, parsed.parsed);
  
  	handleInput(spawned, parsed.opts);
  
  	spawned.then = promise.then.bind(promise);
  	spawned.catch = promise.catch.bind(promise);
  
  	return spawned;
  }

• example usage

  n/a

function execa.shell (cmd, opts)

• description and source-code

  (cmd, opts) => handleShell(module.exports, cmd, opts)

• example usage

  ...
  	console.log(result.stdout);
  	//=> 'unicorns'
  });
  
  // pipe the child process stdout to the current stdout
  execa('echo', ['unicorns']).stdout.pipe(process.stdout);
  
  execa.shell('echo unicorns').then(result => {
  	console.log(result.stdout);
  	//=> 'unicorns'
  });
  
  // example of catching an error
  execa.shell('exit 3').catch(error => {
  	console.log(error);
  ...

function execa.shellSync (cmd, opts)

• description and source-code

  (cmd, opts) => handleShell(module.exports.sync, cmd, opts)

• example usage

  ...
  
  Same options as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ), except the default encoding is `utf8` instead of `buffer`.
  
  Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ).
  
  This method throws an `Error` if the command fails.
  
  ### execa.shellSync(file, [options])
  
  Execute a command synchronously through the system shell.
  
  Same options as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ), except the default encoding is `utf8` instead of `buffer`.
  
  Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ).
  ...

function execa.spawn ()

• description and source-code

  function deprecated() {
    warned = exports.printDeprecationMessage(msg, warned, deprecated);
    if (new.target) {
      return Reflect.construct(fn, arguments, new.target);
    }
    return fn.apply(this, arguments);
  }

• example usage

  ...
  
  	const parsed = handleArgs(cmd, args, opts);
  	const encoding = parsed.opts.encoding;
  	const maxBuffer = parsed.opts.maxBuffer;
  
  	let spawned;
  	try {
  		spawned = childProcess.spawn(parsed.cmd, parsed.args, parsed.opts);
  	} catch (err) {
  		return Promise.reject(err);
  	}
  
  	let removeExitHandler;
  	if (parsed.opts.cleanup) {
  		removeExitHandler = onExit(() => {
  ...

function execa.stderr ()

• description and source-code

  stderr = function () {
  	// TODO: set `stdout: 'ignore'` when that option is implemented
  	return module.exports.apply(null, arguments).then(x => x.stderr);
  }

• example usage

  ...
  
  Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced
   to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
  
  ### execa.stdout(file, [arguments], [options])
  
  Same as `execa()`, but returns only `stdout`.
  
  ### execa.stderr(file, [arguments], [options])
  
  Same as `execa()`, but returns only `stderr`.
  
  ### execa.shell(command, [options])
  
  Execute a command through the system shell. Prefer `execa()` whenever possible, as it's both faster and safer.
  ...

function execa.stdout ()

• description and source-code

  stdout = function () {
  	// TODO: set `stderr: 'ignore'` when that option is implemented
  	return module.exports.apply(null, arguments).then(x => x.stdout);
  }

• example usage

  ...
  
  Same options as [`child_process.spawn`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options
  ).
  
  Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
  
  Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced
   to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
  
  ### execa.stdout(file, [arguments], [options])
  
  Same as `execa()`, but returns only `stdout`.
  
  ### execa.stderr(file, [arguments], [options])
  
  Same as `execa()`, but returns only `stderr`.
  ...

function execa.sync (cmd, args, opts)

• description and source-code

  (cmd, args, opts) => {
  	const parsed = handleArgs(cmd, args, opts);
  
  	if (isStream(parsed.opts.input)) {
  		throw new TypeError('The `input` option cannot be a stream in sync mode');
  	}
  
  	const result = childProcess.spawnSync(parsed.cmd, parsed.args, parsed.opts);
  
  	if (result.error || result.status !== 0) {
  		throw (result.error || new Error(result.stderr === '' ? result.stdout : result.stderr));
  	}
  
  	result.stdout = handleOutput(parsed.opts, result.stdout);
  	result.stderr = handleOutput(parsed.opts, result.stderr);
  
  	return result;
  }

• example usage

  ...
  
  Same options as [`child_process.spawn`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options
  ).
  
  Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess).
  
  The `child_process` instance is enhanced to also be promise for a result object with `stdout` and `stderr` properties.
  
  ### execa.sync(file, [arguments], [options])
  
  Execute a file synchronously.
  
  Same options as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ), except the default encoding is `utf8` instead of `buffer`.
  
  Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ).
  ...

module execa.errname

function execa.errname (uv, code)

• description and source-code

  code => errname(uv, code)

• example usage

  ...
  } catch (err) {
  	console.error('execa/lib/errname: unable to establish process.binding(\'uv\')', err);
  	uv = null;
  }
  
  function errname(uv, code) {
  	if (uv) {
  		return uv.errname(code);
  	}
  
  	if (!(code < 0)) {
  		throw new Error('err >= 0');
  	}
  
  	return `Unknown system error ${code}`;
  ...

function execa.errname.__test__ (uv, code)

• description and source-code

  function errname(uv, code) {
  	if (uv) {
  		return uv.errname(code);
  	}
  
  	if (!(code < 0)) {
  		throw new Error('err >= 0');
  	}
  
  	return `Unknown system error ${code}`;
  }

• example usage

  n/a

module execa.index

function execa.index (cmd, args, opts)

• description and source-code

  (cmd, args, opts) => {
  	let joinedCmd = cmd;
  
  	if (Array.isArray(args) && args.length > 0) {
  		joinedCmd += ' ' + args.join(' ');
  	}
  
  	const parsed = handleArgs(cmd, args, opts);
  	const encoding = parsed.opts.encoding;
  	const maxBuffer = parsed.opts.maxBuffer;
  
  	let spawned;
  	try {
  		spawned = childProcess.spawn(parsed.cmd, parsed.args, parsed.opts);
  	} catch (err) {
  		return Promise.reject(err);
  	}
  
  	let removeExitHandler;
  	if (parsed.opts.cleanup) {
  		removeExitHandler = onExit(() => {
  			spawned.kill();
  		});
  	}
  
  	let timeoutId = null;
  	let timedOut = false;
  
  	const cleanupTimeout = () => {
  		if (timeoutId) {
  			clearTimeout(timeoutId);
  			timeoutId = null;
  		}
  	};
  
  	if (parsed.opts.timeout > 0) {
  		timeoutId = setTimeout(() => {
  			timeoutId = null;
  			timedOut = true;
  			spawned.kill(parsed.killSignal);
  		}, parsed.opts.timeout);
  	}
  
  	const processDone = new Promise(resolve => {
  		spawned.on('exit', (code, signal) => {
  			cleanupTimeout();
  			resolve({code, signal});
  		});
  
  		spawned.on('error', err => {
  			cleanupTimeout();
  			resolve({err});
  		});
  
  		if (spawned.stdin) {
  			spawned.stdin.on('error', err => {
  				cleanupTimeout();
  				resolve({err});
  			});
  		}
  	});
  
  	function destroy() {
  		if (spawned.stdout) {
  			spawned.stdout.destroy();
  		}
  
  		if (spawned.stderr) {
  			spawned.stderr.destroy();
  		}
  	}
  
  	const promise = pFinally(Promise.all([
  		processDone,
  		getStream(spawned, 'stdout', encoding, maxBuffer),
  		getStream(spawned, 'stderr', encoding, maxBuffer)
  	]).then(arr => {
  		const result = arr[0];
  		const stdout = arr[1];
  		const stderr = arr[2];
  
  		let err = result.err;
  		const code = result.code;
  		const signal = result.signal;
  
  		if (removeExitHandler) {
  			removeExitHandler();
  		}
  
  		if (err || code !== 0 || signal !== null) {
  			if (!err) {
  				const output = parsed.opts.stdio === 'inherit' ? '' : `\n${stderr}${stdout}`;
  				err = new Error(`Command failed: ${joinedCmd}${output}`);
  				err.code = code < 0 ? errname(code) : code;
  			}
  
  			// TODO: missing some timeout logic for killed
  			// https://github.com/nodejs/node/blob/master/lib/child_process.js#L203
  			// err.killed = spawned.killed || killed;
  			err.killed = err.killed || spawned.killed;
  
  			err.stdout = stdout;
  			err.stderr = stderr;
  			err.failed = true;
  			err.signal = signal || null;
  			err.cmd = joinedCmd;
  			err.timedOut = timedOut;
  
  			if (!parsed.opts.reject) {
  				return err;
  			}
  
  			throw err;
  		}
  
  		return {
  			stdout: handleOutput(parsed.opts, stdout),
  			stderr: handleOutput(parsed.opts, stderr),
  			code: 0,
  			failed: false,
  			killed: false,
  			signal: null,
  			cmd: joinedCmd,
  			timedOut: false
  		};
  	}), destroy);
  
  	crossSpawn._enoent.hookChildProcess(spawned, parsed.parsed);
  
  	handleInput(spawned, parsed.opts);
  
  	spawned.then = promise.then.bind(promise);
  	spawned.catch = promise.catch.bind(promise);
  
  	return spawned;
  }

• example usage

  n/a

function execa.index.shell (cmd, opts)

• description and source-code

  (cmd, opts) => handleShell(module.exports, cmd, opts)

• example usage

  ...
  	console.log(result.stdout);
  	//=> 'unicorns'
  });
  
  // pipe the child process stdout to the current stdout
  execa('echo', ['unicorns']).stdout.pipe(process.stdout);
  
  execa.shell('echo unicorns').then(result => {
  	console.log(result.stdout);
  	//=> 'unicorns'
  });
  
  // example of catching an error
  execa.shell('exit 3').catch(error => {
  	console.log(error);
  ...

function execa.index.shellSync (cmd, opts)

• description and source-code

  (cmd, opts) => handleShell(module.exports.sync, cmd, opts)

• example usage

  ...
  
  Same options as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ), except the default encoding is `utf8` instead of `buffer`.
  
  Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ).
  
  This method throws an `Error` if the command fails.
  
  ### execa.shellSync(file, [options])
  
  Execute a command synchronously through the system shell.
  
  Same options as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ), except the default encoding is `utf8` instead of `buffer`.
  
  Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ).
  ...

function execa.index.spawn ()

• description and source-code

  function deprecated() {
    warned = exports.printDeprecationMessage(msg, warned, deprecated);
    if (new.target) {
      return Reflect.construct(fn, arguments, new.target);
    }
    return fn.apply(this, arguments);
  }

• example usage

  ...
  
  	const parsed = handleArgs(cmd, args, opts);
  	const encoding = parsed.opts.encoding;
  	const maxBuffer = parsed.opts.maxBuffer;
  
  	let spawned;
  	try {
  		spawned = childProcess.spawn(parsed.cmd, parsed.args, parsed.opts);
  	} catch (err) {
  		return Promise.reject(err);
  	}
  
  	let removeExitHandler;
  	if (parsed.opts.cleanup) {
  		removeExitHandler = onExit(() => {
  ...

function execa.index.stderr ()

• description and source-code

  stderr = function () {
  	// TODO: set `stdout: 'ignore'` when that option is implemented
  	return module.exports.apply(null, arguments).then(x => x.stderr);
  }

• example usage

  ...
  
  Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced
   to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
  
  ### execa.stdout(file, [arguments], [options])
  
  Same as `execa()`, but returns only `stdout`.
  
  ### execa.stderr(file, [arguments], [options])
  
  Same as `execa()`, but returns only `stderr`.
  
  ### execa.shell(command, [options])
  
  Execute a command through the system shell. Prefer `execa()` whenever possible, as it's both faster and safer.
  ...

function execa.index.stdout ()

• description and source-code

  stdout = function () {
  	// TODO: set `stderr: 'ignore'` when that option is implemented
  	return module.exports.apply(null, arguments).then(x => x.stdout);
  }

• example usage

  ...
  
  Same options as [`child_process.spawn`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options
  ).
  
  Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
  
  Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced
   to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties.
  
  ### execa.stdout(file, [arguments], [options])
  
  Same as `execa()`, but returns only `stdout`.
  
  ### execa.stderr(file, [arguments], [options])
  
  Same as `execa()`, but returns only `stderr`.
  ...

function execa.index.sync (cmd, args, opts)

• description and source-code

  (cmd, args, opts) => {
  	const parsed = handleArgs(cmd, args, opts);
  
  	if (isStream(parsed.opts.input)) {
  		throw new TypeError('The `input` option cannot be a stream in sync mode');
  	}
  
  	const result = childProcess.spawnSync(parsed.cmd, parsed.args, parsed.opts);
  
  	if (result.error || result.status !== 0) {
  		throw (result.error || new Error(result.stderr === '' ? result.stdout : result.stderr));
  	}
  
  	result.stdout = handleOutput(parsed.opts, result.stdout);
  	result.stderr = handleOutput(parsed.opts, result.stderr);
  
  	return result;
  }

• example usage

  ...
  
  Same options as [`child_process.spawn`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options
  ).
  
  Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess).
  
  The `child_process` instance is enhanced to also be promise for a result object with `stdout` and `stderr` properties.
  
  ### execa.sync(file, [arguments], [options])
  
  Execute a file synchronously.
  
  Same options as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ), except the default encoding is `utf8` instead of `buffer`.
  
  Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options
  ).
  ...