This lists all available methods and their options. This also describes the properties of the subprocess, result and error they return.
file: string | URL
arguments: string[]
options: Options
Returns: ResultPromise
Executes a command using file ...arguments.
More info on the syntax and escaping.
file: string | URL
arguments: string[]
options: Options
Returns: ResultPromise
Same as execa() but using script-friendly default options.
This is the preferred method when executing multiple commands in a script file.
scriptPath: string | URL
arguments: string[]
options: Options
Returns: ResultPromise
Same as execa() but using the node: true option.
Executes a Node.js file using node scriptPath ...arguments.
This is the preferred method when executing Node.js files.
file: string | URL
arguments: string[]
options: SyncOptions
Returns: SyncResult
Same as execa() and $ but synchronous.
Returns a subprocess result or throws an error. The subprocess is not returned: its methods and properties are not available.
Those methods are discouraged as they hold the CPU and lack multiple features.
command: string
Returns: ResultPromise, SyncResult
Same as execa(), $(), execaNode() and execaSync() but using a template string. command includes both the file and its arguments.
More info on the syntax and escaping.
command: string
options: Options, SyncOptions
Returns: ResultPromise, SyncResult
Same as execa`command` but with options.
options: Options, SyncOptions
Returns: ExecaMethod, ExecaScriptMethod, ExecaNodeMethod, ExecaSyncMethod, ExecaScriptSyncMethod
Returns a new instance of those methods but with different default options. Consecutive calls are merged to previous ones.
command: string
Returns: string[]
Split a command string into an array. For example, 'npm run build' returns ['npm', 'run', 'build'] and 'argument otherArgument' returns ['argument', 'otherArgument'].
message: Message
sendMessageOptions: SendMessageOptions
Returns: Promise<void>
Send a message to the parent process.
This requires the ipc option to be true. The type of message depends on the serialization option.
Type: object
Type: boolean
Default: false
Throw when the other process is not receiving or listening to messages.
getOneMessageOptions: GetOneMessageOptions
Returns: Promise<Message>
Receive a single message from the parent process.
This requires the ipc option to be true. The type of message depends on the serialization option.
Type: object
Type: (Message) => boolean
Ignore any message that returns false.
Type: boolean
Default: true
Keep the subprocess alive while getOneMessage() is waiting.
getEachMessageOptions: GetEachMessageOptions
Returns: AsyncIterable<Message>
Iterate over each message from the parent process.
This requires the ipc option to be true. The type of message depends on the serialization option.
Type: object
Type: boolean
Default: true
Keep the subprocess alive while getEachMessage() is waiting.
Returns: Promise<AbortSignal>
Retrieves the AbortSignal shared by the cancelSignal option.
This can only be called inside a subprocess. This requires the gracefulCancel option to be true.
TypeScript: ResultPromise
Type: Promise<object> | Subprocess
The return value of all asynchronous methods is both:
- the subprocess.
- a
Promiseeither resolving with its successfulresult, or rejecting with itserror.
TypeScript: Subprocess
child_process instance with the following methods and properties.
Returns: AsyncIterable
Subprocesses are async iterables. They iterate over each output line.
readableOptions: ReadableOptions
Returns: AsyncIterable
Same as subprocess[Symbol.asyncIterator] except options can be provided.
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.
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: ResultPromise
pipeOptions: PipeOptions
Returns: Promise<Result>
Like subprocess.pipe(file, arguments?, options?) but using the return value of another execa() call instead.
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.
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: Message
sendMessageOptions: SendMessageOptions
Returns: Promise<void>
Send a message to the subprocess.
This requires the ipc option to be true. The type of message depends on the serialization option.
getOneMessageOptions: GetOneMessageOptions
Returns: Promise<Message>
Receive a single message from the subprocess.
This requires the ipc option to be true. The type of message depends on the serialization option.
getEachMessageOptions: GetEachMessageOptions
Returns: AsyncIterable<Message>
Iterate over each message from the subprocess.
This requires the ipc option to be true. The type of message depends on the serialization option.
Type: Writable | null
The subprocess stdin as a stream.
This is null if the stdin option is set to 'inherit', 'ignore', Readable or integer.
Type: Readable | null
The subprocess stdout as a stream.
This is null if the stdout option is set to 'inherit', 'ignore', Writable or integer, or if the buffer option is false.
Type: Readable | null
The subprocess stderr as a stream.
This is null if the stderr option is set to 'inherit', 'ignore', Writable or integer, or if the buffer option is false.
Type: Readable | undefined
Stream combining/interleaving subprocess.stdout and subprocess.stderr.
This requires the all option to be true.
This is undefined if stdout and stderr options are set to 'inherit', 'ignore', Writable or integer, or if the buffer option is false.
More info on interleaving and streaming.
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, or if the buffer option is false.
readableOptions: ReadableOptions
Returns: Readable Node.js stream
Converts the subprocess to a readable stream.
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, iterates over lines. Each line is a string.
If true, iterates over arbitrary chunks of data. Each line is an Uint8Array (with subprocess.iterable()) or a Buffer (with subprocess.readable()/subprocess.duplex()).
This is always true when the encoding option is binary.
More info for iterables and streams.
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.
writableOptions: WritableOptions
Returns: Writable Node.js stream
Converts the subprocess to a writable stream.
Type: object
Type: "stdin" | "fd3" | "fd4" | ...
Default: "stdin"
Which stream to write to the subprocess. A file descriptor like "fd3" can also be passed.
duplexOptions: ReadableOptions | WritableOptions
Returns: Duplex Node.js stream
Converts the subprocess to a duplex stream.
TypeScript: Result or SyncResult
Type: object
Result of a subprocess successful execution.
When the subprocess fails, it is rejected with an ExecaError instead.
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, or if the buffer option is false.
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, or if the buffer option is false.
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 requires the all option to be true.
This is undefined if both stdout and stderr options are set to only 'inherit', 'ignore', Writable or integer, or if the buffer option is false.
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, or if the buffer option is false.
Items are arrays when their corresponding stdio option is a transform in object mode.
Type: Message[]
All the messages sent by the subprocess to the current process.
This is empty unless the ipc option is true. Also, this is empty if the buffer option is false.
Type: Array<Result | ExecaError>
Results of the other subprocesses that were piped into this subprocess.
This array is initially empty and is populated each time the subprocess.pipe() method resolves.
Type: string
The file and arguments that were run.
Type: string
Same as command but escaped.
Type: string
The current directory in which the command was run.
Type: number
Duration of the subprocess, in milliseconds.
Type: boolean
Whether the subprocess failed to run.
When this is true, the result is an ExecaError instance with additional error-related properties.
Type: Error
Result of a subprocess failed execution.
This error is thrown as an exception. If the reject option is false, it is returned instead.
This has the same shape as successful results, with the following additional properties.
Type: string
Error message when the subprocess failed to run.
Type: string
This is the same as error.message except it does not include the subprocess output.
Type: string | undefined
Original error message. This is the same as error.message excluding the subprocess output and some additional information added by Execa.
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: boolean
Whether the subprocess timed out due to the timeout option.
Type: boolean
Whether the subprocess was canceled using the cancelSignal option.
Type: boolean
Whether the subprocess was canceled using both the cancelSignal and the gracefulCancel options.
Type: boolean
Whether the subprocess failed because its output was larger than the maxBuffer 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 was terminated by the SIGKILL signal sent by the forceKillAfterDelay 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.
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.
TypeScript: Options or SyncOptions
Type: object
This lists all options for execa() and the other methods.
The following options can specify different values for stdout and stderr: verbose, lines, stripFinalNewline, buffer, maxBuffer.
Type: boolean
Default: true with $, false otherwise
Prefer locally installed binaries when looking for a binary to execute.
Type: string | URL
Default: cwd option
Preferred path to find locally installed binaries, when using the preferLocal option.
Type: boolean
Default: true with execaNode(), false otherwise
If true, runs with Node.js. The first argument must be a Node.js file.
The subprocess inherits the current Node.js CLI flags and version. This can be overridden using the nodeOptions and nodePath options.
Type: string[]
Default: process.execArgv (current Node.js CLI flags)
List of CLI flags 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.
Requires the node option to be true.
Type: boolean | string | URL
Default: false
If true, runs the 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.
We recommend against using this option.
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
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: 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.
TypeScript: StdinOption or StdinSyncOption
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', 'overlapped', 'ignore, 'inherit', a file descriptor integer, a Node.js Readable stream, a web ReadableStream, a { file: 'path' } object, a file URL, an Iterable (including an array of strings), an AsyncIterable, an Uint8Array, a generator function, a Duplex or a web TransformStream.
This can be an array of values such as ['inherit', 'pipe'] or [fileUrl, 'pipe'].
More info on available values, streaming and transforms.
TypeScript: StdoutStderrOption or StdoutStderrSyncOption
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', 'overlapped', 'ignore, 'inherit', a file descriptor integer, a Node.js Writable stream, a web WritableStream, a { file: 'path' } object, a file URL, a generator function, a Duplex or a web TransformStream.
This can be an array of values such as ['inherit', 'pipe'] or [fileUrl, 'pipe'].
More info on available values, streaming and transforms.
TypeScript: StdoutStderrOption or StdoutStderrSyncOption
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', 'overlapped', 'ignore, 'inherit', a file descriptor integer, a Node.js Writable stream, a web WritableStream, a { file: 'path' } object, a file URL, a generator function, a Duplex or a web TransformStream.
This can be an array of values such as ['inherit', 'pipe'] or [fileUrl, 'pipe'].
More info on available values, streaming and transforms.
TypeScript: Options['stdio'] or SyncOptions['stdio']
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.
The array can have more than 3 items, to create additional file descriptors beyond stdin/stdout/stderr.
More info on available values, streaming and transforms.
Type: boolean
Default: false
Add a subprocess.all stream and a result.all property.
Type: 'utf8' | 'utf16le' | 'buffer' | 'hex' | 'base64' | 'base64url' | 'latin1' | 'ascii'
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: 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: 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.
By default, this applies to both stdout and stderr, but different values can also be passed.
When reached, error.isMaxBuffer becomes true.
Type: boolean
Default: true
When buffer is false, the result.stdout, result.stderr, result.all and result.stdio properties are not set.
By default, this applies to both stdout and stderr, but different values can also be passed.
Type: boolean
Default: true if the node, ipcInput or gracefulCancel option is set, false otherwise
Enables exchanging messages with the subprocess using subprocess.sendMessage(message), subprocess.getOneMessage() and subprocess.getEachMessage().
The subprocess must be a Node.js file.
Type: 'json' | 'advanced'
Default: 'advanced'
Specify the kind of serialization used for sending messages between subprocesses when using the ipc option.
Type: Message
Sends an IPC message when the subprocess starts.
The subprocess must be a Node.js file. The value's type depends on the serialization option.
Type: 'none' | 'short' | 'full' | Function
Default: 'none'
If verbose is 'short', prints the command on stderr: its file, arguments, duration and (if it failed) error message.
If verbose is 'full' or a function, the command's stdout, stderr and IPC messages are also printed.
A function can be passed to customize logging. Please see this page for more information.
By default, this applies to both stdout and stderr, but different values can also be passed.
Type: boolean
Default: true
Setting this to false resolves the result's promise with the error instead of rejecting it.
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.
On timeout, error.timedOut becomes true.
Type: AbortSignal
When the cancelSignal is aborted, terminate the subprocess using a SIGTERM signal.
When aborted, error.isCanceled becomes true.
Type: boolean
Default:: false
When the cancelSignal option is aborted, do not send any SIGTERM. Instead, abort the AbortSignal returned by getCancelSignal(). The subprocess should use it to terminate gracefully.
The subprocess must be a Node.js file.
When aborted, error.isGracefullyCanceled becomes true.
Type: number | false
Default: 5000
If the subprocess is terminated but does not exit, forcefully exit it by sending SIGKILL.
When this happens, error.isForcefullyTerminated becomes true.
Type: string | number
Default: 'SIGTERM'
Default signal used to terminate the subprocess.
This can be either a name (like 'SIGTERM') or a number (like 9).
Type: boolean
Default: false
Run the subprocess independently from the current process.
Type: boolean
Default: true
Kill the subprocess when the current process exits.
Type: number
Default: current user identifier
Sets the user identifier of the subprocess.
Type: number
Default: current group identifier
Sets the group identifier of the subprocess.
Type: string
Default: file being executed
Value of argv[0] sent to the subprocess.
Type: boolean
Default: true
On Windows, do not create a new console window.
Type: boolean
Default: true if the shell option is true, false otherwise
If false, escapes the command arguments on Windows.
Type: (string, VerboseObject) => string | undefined
Function passed to the verbose option to customize logging.
Type: VerboseObject or SyncVerboseObject
Subprocess event object, for logging purpose, using the verbose option.
Type: string
Event type. This can be:
'command': subprocess start'output':stdout/stderroutput'ipc': IPC output'error': subprocess failure'duration': subprocess success or failure
Type: string
Depending on verboseObject.type, this is:
'command': theresult.escapedCommand'output': one line fromresult.stdoutorresult.stderr'ipc': one IPC message fromresult.ipcOutput'error': theerror.shortMessage'duration': theresult.durationMs
Type: string
The file and arguments that were run. This is the same as result.escapedCommand.
Type: Options or SyncOptions
The options passed to the subprocess.
Type: string
Serial number identifying the subprocess within the current process. It is incremented from '0'.
This is helpful when multiple subprocesses are running at the same time.
This is similar to a PID except it has no maximum limit, which means it never repeats. Also, it is usually shorter.
Type: Date
Event date/time.
Type: Result, SyncResult or undefined
Subprocess result.
This is undefined if verboseObject.type is 'command', 'output' or 'ipc'.
Type: boolean
Whether another subprocess is piped into this subprocess. This is false when result.pipedFrom is empty.
A transform or an array of transforms can be passed to the stdin, stdout, stderr or stdio option.
A transform is either a generator function or a plain object with the following members.
Type: GeneratorFunction<string | Uint8Array | unknown> | AsyncGeneratorFunction<string | Uint8Array | unknown>
Map or filter the input or output of the subprocess.
Type: GeneratorFunction<string | Uint8Array | unknown> | AsyncGeneratorFunction<string | Uint8Array | unknown>
Create additional lines after the last one.
Type: boolean
Default: false
If true, iterate over arbitrary chunks of Uint8Arrays instead of line strings.
Type: boolean
Default: false
If true, keep newlines in each line argument. Also, this allows multiple yields to produces a single line.
Type: boolean
Default: false
If true, allow transformOptions.transform and transformOptions.final to return any type, not just string or Uint8Array.
Previous: 🔍 Differences with Bash and zx
Top: Table of contents