Process execution for humans
This package improves child_process
methods with:
- Promise interface.
- Script interface and template strings, like
zx
. - Improved Windows support, including shebang binaries.
- Executes locally installed binaries without
npx
. - Cleans up subprocesses when the current process ends.
- Redirect
stdin
/stdout
/stderr
from/to files, streams, iterables, strings,Uint8Array
or objects. - Transform
stdin
/stdout
/stderr
with simple functions. - Iterate over each text line output by the subprocess.
- Fail-safe subprocess termination.
- Get interleaved output from
stdout
andstderr
similar to what is printed on the terminal. - Strips the final newline from the output so you don't have to do
stdout.trim()
. - Convenience methods to pipe subprocesses' input and output.
- Verbose mode for debugging.
- More descriptive errors.
- Higher max buffer: 100 MB instead of 1 MB.
npm install execa
import {execa} from 'execa';
const {stdout} = await execa('echo', ['unicorns']);
console.log(stdout);
//=> 'unicorns'
import {execa as execa_} from 'execa';
const execa = execa_({verbose: 'full'});
await execa('echo', ['unicorns']);
//=> 'unicorns'
import {execa} from 'execa';
const arg = 'unicorns';
const {stdout} = await execa`echo ${arg} & rainbows!`;
console.log(stdout);
//=> 'unicorns & rainbows!'
import {execa} from 'execa';
const args = ['unicorns', '&', 'rainbows!'];
const {stdout} = await execa`echo ${args}`;
console.log(stdout);
//=> 'unicorns & rainbows!'
import {execa} from 'execa';
await execa({verbose: 'full'})`echo unicorns`;
//=> 'unicorns'
For more information about Execa scripts, please see this page.
import {$} from 'execa';
const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;
> node file.js
unicorns
rainbows
> NODE_DEBUG=execa node file.js
[19:49:00.360] [0] $ echo unicorns
unicorns
[19:49:00.383] [0] √ (done in 23ms)
[19:49:00.383] [1] $ echo rainbows
rainbows
[19:49:00.404] [1] √ (done in 21ms)
import {execa} from 'execa';
// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns'], {stdout: {file: 'stdout.txt'}});
// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns'], {stderr: {file: 'stderr.txt'}});
// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {stdout: {file: 'all.txt'}, stderr: {file: 'all.txt'}});
import {execa} from 'execa';
// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'
import {execa} from 'execa';
const {stdout} = await execa('echo', ['unicorns'], {stdout: ['pipe', 'inherit']});
// Prints `unicorns`
console.log(stdout);
// Also returns 'unicorns'
import {execa} from 'execa';
// Similar to `npm run build | sort | head -n2` in Bash
const {stdout, pipedFrom} = await execa('npm', ['run', 'build'])
.pipe('sort')
.pipe('head', ['-n2']);
console.log(stdout); // Result of `head -n2`
console.log(pipedFrom[0]); // Result of `sort`
console.log(pipedFrom[0].pipedFrom[0]); // Result of `npm run build`
import {execa} from 'execa';
await execa`npm run build`
.pipe`sort`
.pipe`head -n2`;
import {execa} from 'execa';
for await (const line of execa`npm run build`)) {
if (line.includes('ERROR')) {
console.log(line);
}
}
import {execa} from 'execa';
// Catching an error
try {
await execa('unknown', ['command']);
} catch (error) {
console.log(error);
/*
ExecaError: Command failed with ENOENT: unknown command
spawn unknown ENOENT
at ...
at ... {
shortMessage: 'Command failed with ENOENT: unknown command\nspawn unknown ENOENT',
originalMessage: 'spawn unknown ENOENT',
command: 'unknown command',
escapedCommand: 'unknown command',
cwd: '/path/to/cwd',
durationMs: 28.217566,
failed: true,
timedOut: false,
isCanceled: false,
isTerminated: false,
isMaxBuffer: false,
code: 'ENOENT',
stdout: '',
stderr: '',
stdio: [undefined, '', ''],
pipedFrom: []
[cause]: Error: spawn unknown ENOENT
at ...
at ... {
errno: -2,
code: 'ENOENT',
syscall: 'spawn unknown',
path: 'unknown',
spawnargs: [ 'command' ]
}
}
*/
}
file
: string | URL
arguments
: string[]
options
: Options
Returns: Subprocess
Executes a command using file ...arguments
.
Arguments are automatically escaped. They can contain any character, including spaces, tabs and newlines.
command
: string
options
: Options
Returns: Subprocess
Executes a command. command
is a template string and includes both the file
and its arguments
.
The command
template string can inject any ${value}
with the following types: string, number, subprocess
or an array of those types. For example: execa`echo one ${'two'} ${3} ${['four', 'five']}`
. For ${subprocess}
, the subprocess's stdout
is used.
Arguments are automatically escaped. They can contain any character, but spaces, tabs and newlines must use ${}
like execa`echo ${'has space'}`
.
The command
template string can use multiple lines and indentation.
options
: Options
Returns: execa
Returns a new instance of Execa but with different default options
. Consecutive calls are merged to previous ones.
This allows setting global options or sharing options between multiple commands.
Same as execa()
but synchronous.
Returns or throws a subprocess result
. The subprocess
is not returned: its methods and properties are not available.
The following features cannot be used:
- Streams:
subprocess.stdin
,subprocess.stdout
,subprocess.stderr
,subprocess.readable()
,subprocess.writable()
,subprocess.duplex()
. - The
stdin
,stdout
,stderr
andstdio
options cannot be'overlapped'
, an async iterable, an async transform, aDuplex
, nor a web stream. Node.js streams can be passed but only if either they have a file descriptor, or theinput
option is used. - Signal termination:
subprocess.kill()
,subprocess.pid
,cleanup
option,cancelSignal
option,forceKillAfterDelay
option. - Piping multiple processes:
subprocess.pipe()
. subprocess.iterable()
.ipc
andserialization
options.result.all
is not interleaved.detached
option.- The
maxBuffer
option is always measured in bytes, not in characters, lines nor objects. Also, it ignores transforms and theencoding
option.
file
: string | URL
arguments
: string[]
options
: Options
Returns: Subprocess
Same as execa()
but using the stdin: 'inherit'
and preferLocal: true
options.
Just like execa()
, this can use the template string syntax or bind options. It can also be run synchronously using $.sync()
or $.s()
.
This is the preferred method when executing multiple commands in a script file. For more information, please see this page.
scriptPath
: string | URL
arguments
: string[]
options
: Options
Returns: Subprocess
Same as execa()
but using the node: true
option.
Executes a Node.js file using node scriptPath ...arguments
.
Just like execa()
, this can use the template string syntax or bind options.
This is the preferred method when executing Node.js files.
command
: string
options
: Options
Returns: Subprocess
execa
with the template string syntax allows the file
or the arguments
to be user-defined (by injecting them with ${}
). However, if both the file
and the arguments
are user-defined, and those are supplied as a single string, then execaCommand(command)
must be used instead.
This is only intended for very specific cases, such as a REPL. This should be avoided otherwise.
Just like execa()
, this can bind options. It can also be run synchronously using execaCommandSync()
.
Arguments are automatically escaped. They can contain any character, but spaces must be escaped with a backslash like execaCommand('echo has\\ space')
.
For all the methods above, no shell interpreter (Bash, cmd.exe, etc.) is used unless the shell
option is set. This means shell-specific characters and expressions ($variable
, &&
, ||
, ;
, |
, etc.) have no special meaning and do not need to be escaped.
The return value of all asynchronous methods is both:
- a
Promise
resolving or rejecting with a subprocessresult
. - a
child_process
instance with the following methods and properties.
file
: string | URL
arguments
: string[]
options
: Options
and PipeOptions
Returns: Promise<Result>
Pipe the subprocess' stdout
to a second Execa subprocess' stdin
. This resolves with that second subprocess' result. If either subprocess is rejected, this is rejected with that subprocess' error instead.
This follows the same syntax as execa(file, arguments?, options?)
except both regular options and pipe-specific options can be specified.
This can be called multiple times to chain a series of subprocesses.
Multiple subprocesses can be piped to the same subprocess. Conversely, the same subprocess can be piped to multiple other subprocesses.
command
: string
options
: Options
and PipeOptions
Returns: Promise<Result>
Like subprocess.pipe(file, arguments?, options?)
but using a command
template string instead. This follows the same syntax as execa
template strings.
secondSubprocess
: execa()
return value
pipeOptions
: PipeOptions
Returns: Promise<Result>
Like subprocess.pipe(file, arguments?, options?)
but using the return value of another execa()
call instead.
This is the most advanced method to pipe subprocesses. It is useful in specific cases, such as piping multiple subprocesses to the same subprocess.
Type: object
Type: "stdout" | "stderr" | "all" | "fd3" | "fd4" | ...
Default: "stdout"
Which stream to pipe from the source subprocess. A file descriptor like "fd3"
can also be passed.
"all"
pipes both stdout
and stderr
. This requires the all
option to be true
.
Type: "stdin" | "fd3" | "fd4" | ...
Default: "stdin"
Which stream to pipe to the destination subprocess. A file descriptor like "fd3"
can also be passed.
Type: AbortSignal
Unpipe the subprocess when the signal aborts.
The subprocess.pipe()
method will be rejected with a cancellation error.
signal
: string | number
error
: Error
Returns: boolean
Sends a signal to the subprocess. The default signal is the killSignal
option. killSignal
defaults to SIGTERM
, which terminates the subprocess.
This returns false
when the signal could not be sent, for example when the subprocess has already exited.
When an error is passed as argument, it is set to the subprocess' error.cause
. The subprocess is then terminated with the default signal. This does not emit the error
event.
Type: number | undefined
Process identifier (PID).
This is undefined
if the subprocess failed to spawn.
message
: unknown
Returns: boolean
Send a message
to the subprocess. The type of message
depends on the serialization
option.
The subprocess receives it as a message
event.
This returns true
on success.
This requires the ipc
option to be true
.
message
: unknown
Receives a message
from the subprocess. The type of message
depends on the serialization
option.
The subprocess sends it using process.send(message)
.
This requires the ipc
option to be true
.
Type: Writable | null
The subprocess stdin
as a stream.
This is null
if the stdin
option is set to 'inherit'
, 'ignore'
, Readable
or integer
.
This is intended for advanced cases. Please consider using the stdin
option, input
option, inputFile
option, or subprocess.pipe()
instead.
Type: Readable | null
The subprocess stdout
as a stream.
This is null
if the stdout
option is set to 'inherit'
, 'ignore'
, Writable
or integer
.
This is intended for advanced cases. Please consider using result.stdout
, the stdout
option, subprocess.iterable()
, or subprocess.pipe()
instead.
Type: Readable | null
The subprocess stderr
as a stream.
This is null
if the stderr
option is set to 'inherit'
, 'ignore'
, Writable
or integer
.
This is intended for advanced cases. Please consider using result.stderr
, the stderr
option, subprocess.iterable()
, or subprocess.pipe()
instead.
Type: Readable | undefined
Stream combining/interleaving subprocess.stdout
and subprocess.stderr
.
This is undefined
if either:
- the
all
option isfalse
(the default value). - both
stdout
andstderr
options are set to'inherit'
,'ignore'
,Writable
orinteger
.
This is intended for advanced cases. Please consider using result.all
, the stdout
/stderr
option, subprocess.iterable()
, or subprocess.pipe()
instead.
Type: [Writable | null, Readable | null, Readable | null, ...Array<Writable | Readable | null>]
The subprocess stdin
, stdout
, stderr
and other files descriptors as an array of streams.
Each array item is null
if the corresponding stdin
, stdout
, stderr
or stdio
option is set to 'inherit'
, 'ignore'
, Stream
or integer
.
This is intended for advanced cases. Please consider using result.stdio
, the stdio
option, subprocess.iterable()
or subprocess.pipe()
instead.
Returns: AsyncIterable
Subprocesses are async iterables. They iterate over each output line.
The iteration waits for the subprocess to end. It throws if the subprocess fails. This means you do not need to await
the subprocess' promise.
readableOptions
: ReadableOptions
Returns: AsyncIterable
Same as subprocess[Symbol.asyncIterator]
except options can be provided.
readableOptions
: ReadableOptions
Returns: Readable
Node.js stream
Converts the subprocess to a readable stream.
Unlike subprocess.stdout
, the stream waits for the subprocess to end and emits an error
event if the subprocess fails. This means you do not need to await
the subprocess' promise. On the other hand, you do need to handle to the stream error
event. This can be done by using await finished(stream)
, await pipeline(..., stream)
or await text(stream)
which throw an exception when the stream errors.
Before using this method, please first consider the stdin
/stdout
/stderr
/stdio
options, subprocess.pipe()
or subprocess.iterable()
.
writableOptions
: WritableOptions
Returns: Writable
Node.js stream
Converts the subprocess to a writable stream.
Unlike subprocess.stdin
, the stream waits for the subprocess to end and emits an error
event if the subprocess fails. This means you do not need to await
the subprocess' promise. On the other hand, you do need to handle to the stream error
event. This can be done by using await finished(stream)
or await pipeline(stream, ...)
which throw an exception when the stream errors.
Before using this method, please first consider the stdin
/stdout
/stderr
/stdio
options or subprocess.pipe()
.
duplexOptions
: ReadableOptions | WritableOptions
Returns: Duplex
Node.js stream
Converts the subprocess to a duplex stream.
The stream waits for the subprocess to end and emits an error
event if the subprocess fails. This means you do not need to await
the subprocess' promise. On the other hand, you do need to handle to the stream error
event. This can be done by using await finished(stream)
, await pipeline(..., stream, ...)
or await text(stream)
which throw an exception when the stream errors.
Before using this method, please first consider the stdin
/stdout
/stderr
/stdio
options, subprocess.pipe()
or subprocess.iterable()
.
Type: object
Type: "stdout" | "stderr" | "all" | "fd3" | "fd4" | ...
Default: "stdout"
Which stream to read from the subprocess. A file descriptor like "fd3"
can also be passed.
"all"
reads both stdout
and stderr
. This requires the all
option to be true
.
Type: boolean
Default: false
with subprocess.iterable()
, true
with subprocess.readable()
/subprocess.duplex()
If false
, the stream iterates over lines. Each line is a string. Also, the stream is in object mode.
If true
, the stream iterates over arbitrary chunks of data. Each line is an Uint8Array
(with subprocess.iterable()
) or a Buffer
(otherwise).
This is always true
when the encoding
option is binary.
Type: boolean
Default: false
with subprocess.iterable()
, true
with subprocess.readable()
/subprocess.duplex()
If both this option and the binary
option is false
, newlines are stripped from each line.
Type: object
Type: "stdin" | "fd3" | "fd4" | ...
Default: "stdin"
Which stream to write to the subprocess. A file descriptor like "fd3"
can also be passed.
Type: object
Result of a subprocess execution.
When the subprocess fails, it is rejected with an ExecaError
instead.
Type: string
The file and arguments that were run, for logging purposes.
This is not escaped and should not be executed directly as a subprocess, including using execa()
or execaCommand()
.
Type: string
Same as command
but escaped.
Unlike command
, control characters are escaped, which makes it safe to print in a terminal.
This can also be copied and pasted into a shell, for debugging purposes.
Since the escaping is fairly basic, this should not be executed directly as a subprocess, including using execa()
or execaCommand()
.
Type: string
The current directory in which the command was run.
Type: number
Duration of the subprocess, in milliseconds.
Type: string | Uint8Array | string[] | Uint8Array[] | unknown[] | undefined
The output of the subprocess on stdout
.
This is undefined
if the stdout
option is set to only 'inherit'
, 'ignore'
, Writable
or integer
. This is an array if the lines
option is true
, or if the stdout
option is a transform in object mode.
Type: string | Uint8Array | string[] | Uint8Array[] | unknown[] | undefined
The output of the subprocess on stderr
.
This is undefined
if the stderr
option is set to only 'inherit'
, 'ignore'
, Writable
or integer
. This is an array if the lines
option is true
, or if the stderr
option is a transform in object mode.
Type: string | Uint8Array | string[] | Uint8Array[] | unknown[] | undefined
The output of the subprocess with result.stdout
and result.stderr
interleaved.
This is undefined
if either:
- the
all
option isfalse
(the default value). - both
stdout
andstderr
options are set to only'inherit'
,'ignore'
,Writable
orinteger
.
This is an array if the lines
option is true
, or if either the stdout
or stderr
option is a transform in object mode.
Type: Array<string | Uint8Array | string[] | Uint8Array[] | unknown[] | undefined>
The output of the subprocess on stdin
, stdout
, stderr
and other file descriptors.
Items are undefined
when their corresponding stdio
option is set to 'inherit'
, 'ignore'
, Writable
or integer
. Items are arrays when their corresponding stdio
option is a transform in object mode.
Type: boolean
Whether the subprocess failed to run.
Type: boolean
Whether the subprocess timed out.
Type: boolean
Whether the subprocess was canceled using the cancelSignal
option.
Type: boolean
Whether the subprocess was terminated by a signal (like SIGTERM
) sent by either:
- The current process.
- Another process. This case is not supported on Windows.
Type: boolean
Whether the subprocess failed because its output was larger than the maxBuffer
option.
Type: number | undefined
The numeric exit code of the subprocess that was run.
This is undefined
when the subprocess could not be spawned or was terminated by a signal.
Type: string | undefined
The name of the signal (like SIGTERM
) that terminated the subprocess, sent by either:
- The current process.
- Another process. This case is not supported on Windows.
If a signal terminated the subprocess, this property is defined and included in the error message. Otherwise it is undefined
.
Type: string | undefined
A human-friendly description of the signal that was used to terminate the subprocess. For example, Floating point arithmetic error
.
If a signal terminated the subprocess, this property is defined and included in the error message. Otherwise it is undefined
. It is also undefined
when the signal is very uncommon which should seldomly happen.
Type: Array<Result | ExecaError>
Results of the other subprocesses that were piped into this subprocess. This is useful to inspect a series of subprocesses piped with each other.
This array is initially empty and is populated each time the subprocess.pipe()
method resolves.
Type: Error
Exception thrown when the subprocess fails, either:
- its exit code is not
0
- it was terminated with a signal, including
subprocess.kill()
- timing out
- being canceled
- there's not enough memory or there are already too many subprocesses
This has the same shape as successful results, with the following additional properties.
Type: string
Error message when the subprocess failed to run. In addition to the underlying error message, it also contains some information related to why the subprocess errored.
The subprocess stderr
, stdout
and other file descriptors' output are appended to the end, separated with newlines and not interleaved.
Type: string
This is the same as the message
property except it does not include the subprocess stdout
/stderr
/stdio
.
Type: string | undefined
Original error message. This is the same as the message
property excluding the subprocess stdout
/stderr
/stdio
and some additional information added by Execa.
This exists only if the subprocess exited due to an error
event or a timeout.
Type: unknown | undefined
Underlying error, if there is one. For example, this is set by subprocess.kill(error)
.
This is usually an Error
instance.
Type: string | undefined
Node.js-specific error code, when available.
Type: object
This lists all options for execa()
and the other methods.
Some options are related to the subprocess output: verbose
, lines
, stripFinalNewline
, buffer
, maxBuffer
. By default, those options apply to all file descriptors (stdout
, stderr
, etc.). A plain object can be passed instead to apply them to only stdout
, stderr
, fd3
, etc.
await execa('./run.js', {verbose: 'full'}) // Same value for stdout and stderr
await execa('./run.js', {verbose: {stdout: 'none', stderr: 'full'}}) // Different values
Type: boolean
Default: true
Setting this to false
resolves the promise with the error instead of rejecting it.
Type: boolean | string | URL
Default: false
If true
, runs file
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.
We recommend against using this option since it is:
- not cross-platform, encouraging shell-specific syntax.
- slower, because of the additional shell interpretation.
- unsafe, potentially allowing command injection.
Type: string | URL
Default: process.cwd()
Current working directory of the subprocess.
This is also used to resolve the nodePath
option when it is a relative path.
Type: object
Default: process.env
Environment key-value pairs.
Unless the extendEnv
option is false
, the subprocess also uses the current process' environment variables (process.env
).
Type: boolean
Default: true
If true
, the subprocess uses both the env
option and the current process' environment variables (process.env
).
If false
, only the env
option is used, not process.env
.
Type: boolean
Default: true
with $
, false
otherwise
Prefer locally installed binaries when looking for a binary to execute.
If you $ npm install foo
, you can then execa('foo')
.
Type: string | URL
Default: process.cwd()
Preferred path to find locally installed binaries in (use with preferLocal
).
Type: boolean
Default: true
with execaNode()
, false
otherwise
If true
, runs with Node.js. The first argument must be a Node.js file.
Type: string[]
Default: process.execArgv
(current Node.js CLI options)
List of CLI options passed to the Node.js executable.
Requires the node
option to be true
.
Type: string | URL
Default: process.execPath
(current Node.js executable)
Path to the Node.js executable.
For example, this can be used together with get-node
to run a specific Node.js version.
Requires the node
option to be true
.
Type: 'none' | 'short' | 'full'
Default: 'none'
If verbose
is 'short'
or 'full'
, prints each command on stderr
before executing it. When the command completes, prints its duration and (if it failed) its error.
If verbose
is 'full'
, the command's stdout
and stderr
are printed too, unless either:
- the
stdout
/stderr
option isignore
orinherit
. - the
stdout
/stderr
is redirected to a stream, a file, a file descriptor, or another subprocess. - the
encoding
option is binary.
This can also be set to 'full'
by setting the NODE_DEBUG=execa
environment variable in the current process.
By default, this applies to both stdout
and stderr
, but different values can also be passed.
Type: boolean
Default: true
Whether to return the subprocess' output using the result.stdout
, result.stderr
, result.all
and result.stdio
properties.
On failure, the error.stdout
, error.stderr
, error.all
and error.stdio
properties are used instead.
When buffer
is false
, the output can still be read using the subprocess.stdout
, subprocess.stderr
, subprocess.stdio
and subprocess.all
streams. If the output is read, this should be done right away to avoid missing any data.
By default, this applies to both stdout
and stderr
, but different values can also be passed.
Type: string | Uint8Array | stream.Readable
Write some input to the subprocess' stdin
.
See also the inputFile
and stdin
options.
Type: string | URL
Use a file as input to the subprocess' stdin
.
See also the input
and stdin
options.
Type: string | number | stream.Readable | ReadableStream | TransformStream | URL | {file: string} | Uint8Array | Iterable<string | Uint8Array | unknown> | AsyncIterable<string | Uint8Array | unknown> | GeneratorFunction<string | Uint8Array | unknown> | AsyncGeneratorFunction<string | Uint8Array | unknown> | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream}
(or a tuple of those types)
Default: inherit
with $
, pipe
otherwise
How to setup the subprocess' standard input. This can be:
'pipe'
: Setssubprocess.stdin
stream.'overlapped'
: Like'pipe'
but asynchronous on Windows.'ignore'
: Do not usestdin
.'inherit'
: Re-use the current process'stdin
.- an integer: Re-use a specific file descriptor from the current process.
- a Node.js
Readable
stream. { file: 'path' }
object.- a file URL.
- a web
ReadableStream
. - an
Iterable
or anAsyncIterable
- an
Uint8Array
.
This can be an array of values such as ['inherit', 'pipe']
or [filePath, 'pipe']
.
This can also be a generator function, a Duplex
or a web TransformStream
to transform the input. Learn more.
Type: string | number | stream.Writable | WritableStream | TransformStream | URL | {file: string} | GeneratorFunction<string | Uint8Array | unknown> | AsyncGeneratorFunction<string | Uint8Array | unknown> | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream}
(or a tuple of those types)
Default: pipe
How to setup the subprocess' standard output. This can be:
'pipe'
: Setsresult.stdout
(as a string orUint8Array
) andsubprocess.stdout
(as a stream).'overlapped'
: Like'pipe'
but asynchronous on Windows.'ignore'
: Do not usestdout
.'inherit'
: Re-use the current process'stdout
.- an integer: Re-use a specific file descriptor from the current process.
- a Node.js
Writable
stream. { file: 'path' }
object.- a file URL.
- a web
WritableStream
.
This can be an array of values such as ['inherit', 'pipe']
or [filePath, 'pipe']
.
This can also be a generator function, a Duplex
or a web TransformStream
to transform the output. Learn more.
Type: string | number | stream.Writable | WritableStream | TransformStream | URL | {file: string} | GeneratorFunction<string | Uint8Array | unknown> | AsyncGeneratorFunction<string | Uint8Array | unknown> | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream}
(or a tuple of those types)
Default: pipe
How to setup the subprocess' standard error. This can be:
'pipe'
: Setsresult.stderr
(as a string orUint8Array
) andsubprocess.stderr
(as a stream).'overlapped'
: Like'pipe'
but asynchronous on Windows.'ignore'
: Do not usestderr
.'inherit'
: Re-use the current process'stderr
.- an integer: Re-use a specific file descriptor from the current process.
- a Node.js
Writable
stream. { file: 'path' }
object.- a file URL.
- a web
WritableStream
.
This can be an array of values such as ['inherit', 'pipe']
or [filePath, 'pipe']
.
This can also be a generator function, a Duplex
or a web TransformStream
to transform the output. Learn more.
Type: string | Array<string | number | stream.Readable | stream.Writable | ReadableStream | WritableStream | TransformStream | URL | {file: string} | Uint8Array | Iterable<string> | Iterable<Uint8Array> | Iterable<unknown> | AsyncIterable<string | Uint8Array | unknown> | GeneratorFunction<string | Uint8Array | unknown> | AsyncGeneratorFunction<string | Uint8Array | unknown> | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream}>
(or a tuple of those types)
Default: pipe
Like the stdin
, stdout
and stderr
options but for all file descriptors at once. For example, {stdio: ['ignore', 'pipe', 'pipe']}
is the same as {stdin: 'ignore', stdout: 'pipe', stderr: 'pipe'}
.
A single string can be used as a shortcut. For example, {stdio: 'pipe'}
is the same as {stdin: 'pipe', stdout: 'pipe', stderr: 'pipe'}
.
The array can have more than 3 items, to create additional file descriptors beyond stdin
/stdout
/stderr
. For example, {stdio: ['pipe', 'pipe', 'pipe', 'pipe']}
sets a fourth file descriptor.
Type: boolean
Default: false
Add a subprocess.all
stream and a result.all
property. They contain the combined/interleaved output of the subprocess' stdout
and stderr
.
Type: boolean
Default: false
Set result.stdout
, result.stderr
, result.all
and result.stdio
as arrays of strings, splitting the subprocess' output into lines.
This cannot be used if the encoding
option is binary.
By default, this applies to both stdout
and stderr
, but different values can also be passed.
Type: string
Default: 'utf8'
If the subprocess outputs text, specifies its character encoding, either 'utf8'
or 'utf16le'
.
If it outputs binary data instead, this should be either:
'buffer'
: returns the binary output as anUint8Array
.'hex'
,'base64'
,'base64url'
,'latin1'
or'ascii'
: encodes the binary output as a string.
The output is available with result.stdout
, result.stderr
and result.stdio
.
Type: boolean
Default: true
Strip the final newline character from the output.
If the lines
option is true, this applies to each output line instead.
By default, this applies to both stdout
and stderr
, but different values can also be passed.
Type: number
Default: 100_000_000
Largest amount of data allowed on stdout
, stderr
and stdio
.
When this threshold is hit, the subprocess fails and error.isMaxBuffer
becomes true
.
This is measured:
- By default: in characters.
- If the
encoding
option is'buffer'
: in bytes. - If the
lines
option istrue
: in lines. - If a transform in object mode is used: in objects.
By default, this applies to both stdout
and stderr
, but different values can also be passed.
Type: boolean
Default: true
if the node
option is enabled, false
otherwise
Enables exchanging messages with the subprocess using subprocess.send(message)
and subprocess.on('message', (message) => {})
.
Type: string
Default: 'advanced'
Specify the kind of serialization used for sending messages between subprocesses when using the ipc
option:
json
: UsesJSON.stringify()
andJSON.parse()
.advanced
: Usesv8.serialize()
Type: boolean
Default: false
Prepare subprocess to run independently of the current process. Specific behavior depends on the platform.
Type: boolean
Default: true
Kill the subprocess when the current process exits unless either:
- the subprocess is
detached
. - the current process is terminated abruptly, for example, with
SIGKILL
as opposed toSIGTERM
or a normal exit.
Type: number
Default: 0
If timeout
is greater than 0
, the subprocess will be terminated if it runs for longer than that amount of milliseconds.
Type: AbortSignal
You can abort the subprocess using AbortController
.
When AbortController.abort()
is called, result.isCanceled
becomes true
.
Type: number | false
Default: 5000
If the subprocess is terminated but does not exit, forcefully exit it by sending SIGKILL
.
The grace period is 5 seconds by default. This feature can be disabled with false
.
This works when the subprocess is terminated by either:
- the
cancelSignal
,timeout
,maxBuffer
orcleanup
option - calling
subprocess.kill()
with no arguments
This does not work when the subprocess is terminated by either:
- calling
subprocess.kill()
with an argument - calling
process.kill(subprocess.pid)
- sending a termination signal from another process
Also, this does not work on Windows, because Windows doesn't support signals: SIGKILL
and SIGTERM
both terminate the subprocess immediately. Other packages (such as taskkill
) can be used to achieve fail-safe termination on Windows.
Type: string | number
Default: SIGTERM
Signal used to terminate the subprocess when:
- using the
cancelSignal
,timeout
,maxBuffer
orcleanup
option - calling
subprocess.kill()
with no arguments
This can be either a name (like "SIGTERM"
) or a number (like 9
).
Type: string
Explicitly set the value of argv[0]
sent to the subprocess. This will be set to file
if not specified.
Type: number
Sets the user identity of the subprocess.
Type: number
Sets the group identity of the subprocess.
Type: boolean
Default: false
If true
, no quoting or escaping of arguments is done on Windows. Ignored on other platforms. This is set to true
automatically when the shell
option is true
.
Type: boolean
Default: true
On Windows, do not create a new console window. Please note this also prevents CTRL-C
from working on Windows.
The stdin
, stdout
and stderr
options can be an array of values.
The following example redirects stdout
to both the terminal and an output.txt
file, while also retrieving its value programmatically.
const {stdout} = await execa('npm', ['install'], {stdout: ['inherit', './output.txt', 'pipe']});
console.log(stdout);
When combining inherit
with other values, please note that the subprocess will not be an interactive TTY, even if the current process is one.
When passing a Node.js stream to the stdin
, stdout
or stderr
option, Node.js requires that stream to have an underlying file or socket, such as the streams created by the fs
, net
or http
core modules. Otherwise the following error is thrown.
TypeError [ERR_INVALID_ARG_VALUE]: The argument 'stdio' is invalid.
This limitation can be worked around by passing either:
- a web stream (
ReadableStream
orWritableStream
) [nodeStream, 'pipe']
instead ofnodeStream
- await execa(..., {stdout: nodeStream});
+ await execa(..., {stdout: [nodeStream, 'pipe']});
Safely handle failures by using automatic retries and exponential backoff with the p-retry
package:
import pRetry from 'p-retry';
const run = async () => {
const results = await execa('curl', ['-sSL', 'https://sindresorhus.com/unicorn']);
return results;
};
console.log(await pRetry(run, {retries: 5}));
import {execa} from 'execa';
const abortController = new AbortController();
const subprocess = execa('node', [], {cancelSignal: abortController.signal});
setTimeout(() => {
abortController.abort();
}, 1000);
try {
await subprocess;
} catch (error) {
console.log(error.isTerminated); // true
console.log(error.isCanceled); // true
}
Execa can be combined with get-bin-path
to test the current package's binary. As opposed to hard-coding the path to the binary, this validates that the package.json
bin
field is correctly set up.
import {getBinPath} from 'get-bin-path';
const binPath = await getBinPath();
await execa(binPath);
The subprocess.all
stream and result.all
string/Uint8Array
property are guaranteed to interleave stdout
and stderr
.
However, for performance reasons, the subprocess might buffer and merge multiple simultaneous writes to stdout
or stderr
. This prevents proper interleaving.
For example, this prints 1 3 2
instead of 1 2 3
because both console.log()
are merged into a single write.
import {execa} from 'execa';
const {all} = await execa('node', ['example.js'], {all: true});
console.log(all);
// example.js
console.log('1'); // writes to stdout
console.error('2'); // writes to stderr
console.log('3'); // writes to stdout
This can be worked around by using setTimeout()
.
import {setTimeout} from 'timers/promises';
console.log('1');
console.error('2');
await setTimeout(0);
console.log('3');
- gulp-execa - Gulp plugin for Execa
- nvexeca - Run Execa using any Node.js version