execa

A better child_process

Why

• Promise interface.
• Strips EOF from the output so you don't have to stdout.trim().
• Supports shebang binaries cross-platform.
• Improved Windows support.
• Higher max buffer. 10 MB instead of 200 KB.
• Executes locally installed binaries by name.
• Cleans up spawned processes when the parent process dies.

Install

$ npm install --save execa

Usage

const execa = require('execa');

execa('echo', ['unicorns']).then(result => {
	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);
	/*
	{
		message: 'Command failed: /bin/sh -c exit 3'
		killed: false,
		code: 3,
		signal: null,
		cmd: '/bin/sh -c exit 3',
		stdout: '',
		stderr: '',
		timedOut: false
	}
	*/
});

API

execa(file, [arguments], [options])

Execute a file.

Think of this as a mix of child_process.execFile and child_process.spawn.

Returns a child_process instance, 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.

Returns a child_process instance.

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.

Returns the same result object as child_process.spawnSync.

This method throws an Error if the command fails.

execa.shellSync(file, [options])

Execute a command synchronously through the system shell.

Returns the same result object as child_process.spawnSync.

options

Type: Object

cwd

Type: string
Default: process.cwd()

Current working directory of the child process.

env

Type: Object
Default: process.env

Environment key-value pairs. Extends automatically from process.env. Set extendEnv to false if you don't want this.

extendEnv

Type: boolean
Default: true

Set to false if you don't want to extend the environment variables when providing the env property.

argv0

Type: string

Explicitly set the value of argv[0] sent to the child process. This will be set to command or file if not specified.

stdio

Type: Array string
Default: pipe

Child's stdio configuration.

detached

Type: boolean

Prepare child to run independently of its parent process. Specific behavior depends on the platform.

uid

Type: number

Sets the user identity of the process.

gid

Type: number

Sets the group identity of the process.

shell

Type: boolean string
Default: false

If true, runs command inside of a shell. Uses /bin/sh on UNIX and cmd.exe on Windows. A different shell can be specified as a string. The shell should understand the -c switch on UNIX or /d /s /c on Windows.

stripEof

Type: boolean
Default: true

Strip EOF (last newline) from the output.

preferLocal

Type: boolean
Default: true

Prefer locally installed binaries when looking for a binary to execute.
If you $ npm install foo, you can then execa('foo').

localDir

Type: string
Default: process.cwd()

Preferred path to find locally installed binaries in (use with preferLocal).

input

Type: string Buffer stream.Readable

Write some input to the stdin of your binary.
Streams are not allowed when using the synchronous methods.

reject

Type: boolean
Default: true

Setting this to false resolves the promise with the error instead of rejecting it.

cleanup

Type: boolean
Default: true

Keep track of the spawned process and kill it when the parent process exits.

encoding

Type: string
Default: utf8

Specify the character encoding used to decode the stdout and stderr output.

timeout

Type: number
Default: 0

If timeout is greater than 0, the parent will send the signal identified by the killSignal property (the default is SIGTERM) if the child runs longer than timeout milliseconds.

maxBuffer

Type: number
Default: 10000000 (10MB)

Largest amount of data in bytes allowed on stdout or stderr.

killSignal

Type: string number
Default: SIGTERM

Signal value to be used when the spawned process will be killed.

stdin

Type: string number Stream undefined null
Default: pipe

Same options as stdio.

stdout

Type: string number Stream undefined null
Default: pipe

Same options as stdio.

stderr

Type: string number Stream undefined null
Default: pipe

Same options as stdio.

Tips

Save and pipe output from a child process

Let's say you want to show the output of a child process in real-time while also saving it to a variable.

const execa = require('execa');
const getStream = require('get-stream');

const stream = execa('echo', ['foo']).stdout;

stream.pipe(process.stdout);

getStream(stream).then(value => {
	console.log('child output:', value);
});

License

MIT © Sindre Sorhus