📔 API reference

September 7, 2024 · View on GitHub

📔 API reference

This lists all available methods and their options. This also describes the properties of the subprocess, result and error they return.

Methods

execa(file, arguments?, options?)

file: string | URL
arguments: string[]
options: Options
Returns: ResultPromise

Executes a command using file ...arguments.

More info on the syntax and escaping.

$(file, arguments?, options?)

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.

More info.

execaNode(scriptPath, arguments?, options?)

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.

More info.

execaSync(file, arguments?, options?)

$.sync(file, arguments?, options?)

$.s(file, arguments?, options?)

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.

More info.

$.s`command`

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.

$.s(options)`command`

command: string
options: Options, SyncOptions
Returns: ResultPromise, SyncResult

Same as execa`command` but with options.

More info.

$.s(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.

More info.

parseCommandString(command)

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'].

More info.

sendMessage(message, sendMessageOptions?)

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.

More info.

sendMessageOptions.strict

Type: boolean
Default: false

Throw when the other process is not receiving or listening to messages.

More info.

getOneMessage(getOneMessageOptions?)

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.

More info.

getOneMessageOptions.filter

Type: (Message) => boolean

Ignore any message that returns false.

More info.

getOneMessageOptions.reference

Type: boolean
Default: true

Keep the subprocess alive while getOneMessage() is waiting.

More info.

getEachMessage(getEachMessageOptions?)

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.

More info.

getEachMessageOptions.reference

Type: boolean
Default: true

Keep the subprocess alive while getEachMessage() is waiting.

More info.

getCancelSignal()

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.

More info.

Return value

TypeScript: ResultPromise
Type: Promise<object> | Subprocess

The return value of all asynchronous methods is both:

the subprocess.
a Promise either resolving with its successful result, or rejecting with its error.

More info.

Subprocess

TypeScript: Subprocess

child_process instance with the following methods and properties.

subprocess[Symbol.asyncIterator]()

Returns: AsyncIterable

Subprocesses are async iterables. They iterate over each output line.

More info.

subprocess.iterable(readableOptions?)

readableOptions: ReadableOptions
Returns: AsyncIterable

Same as subprocess[Symbol.asyncIterator] except options can be provided.

More info.

subprocess.pipe(file, arguments?, options?)

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.

More info.

subprocess.pipe`command`

subprocess.pipe(options)`command`

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.

More info.

subprocess.pipe(secondSubprocess, pipeOptions?)

secondSubprocess: ResultPromise
pipeOptions: PipeOptions
Returns: Promise<Result>

Like subprocess.pipe(file, arguments?, options?) but using the return value of another execa() call instead.

More info.

pipeOptions

Type: object

pipeOptions.from

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.

More info.

pipeOptions.to

Type: "stdin" | "fd3" | "fd4" | ...
Default: "stdin"

Which stream to pipe to the destination subprocess. A file descriptor like "fd3" can also be passed.

More info.

pipeOptions.unpipeSignal

Type: AbortSignal

Unpipe the subprocess when the signal aborts.

More info.

subprocess.kill(signal, error?)

subprocess.kill(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.

More info.

subprocess.pid

Type: number | undefined

Process identifier (PID).

This is undefined if the subprocess failed to spawn.

More info.

subprocess.sendMessage(message, sendMessageOptions)

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.

More info.

subprocess.getOneMessage(getOneMessageOptions?)

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.

More info.

subprocess.getEachMessage(getEachMessageOptions?)

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.

More info.

subprocess.stdin

Type: Writable | null

The subprocess stdin as a stream.

This is null if the stdin option is set to 'inherit', 'ignore', Readable or integer.

More info.

subprocess.stdout

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.

More info.

subprocess.stderr

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.

More info.

subprocess.all

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.

subprocess.stdio

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.

More info.

subprocess.readable(readableOptions?)

readableOptions: ReadableOptions
Returns: Readable Node.js stream

Converts the subprocess to a readable stream.

More info.

readableOptions

Type: object

readableOptions.from

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.

More info.

readableOptions.binary

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.

readableOptions.preserveNewlines

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.

More info.

subprocess.writable(writableOptions?)

writableOptions: WritableOptions
Returns: Writable Node.js stream

Converts the subprocess to a writable stream.

More info.

writableOptions

Type: object

writableOptions.to

Type: "stdin" | "fd3" | "fd4" | ...
Default: "stdin"

Which stream to write to the subprocess. A file descriptor like "fd3" can also be passed.

More info.

subprocess.duplex(duplexOptions?)

duplexOptions: ReadableOptions | WritableOptions
Returns: Duplex Node.js stream

Converts the subprocess to a duplex stream.

More info.

Result

TypeScript: Result or SyncResult
Type: object

Result of a subprocess successful execution.

When the subprocess fails, it is rejected with an ExecaError instead.

result.stdout

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.

More info.

result.stderr

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.

More info.

result.all

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.

More info.

result.stdio

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.

More info.

result.ipcOutput

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.

More info.

result.pipedFrom

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.

More info.

result.command

Type: string

The file and arguments that were run.

More info.

result.escapedCommand

Type: string

Same as command but escaped.

More info.

result.cwd

Type: string

The current directory in which the command was run.

More info.

result.durationMs

Type: number

Duration of the subprocess, in milliseconds.

More info.

result.failed

Type: boolean

Whether the subprocess failed to run.

When this is true, the result is an ExecaError instance with additional error-related properties.

More info.

ExecaError

ExecaSyncError

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.

More info.

error.message

Type: string

Error message when the subprocess failed to run.

More info.

error.shortMessage

Type: string

This is the same as error.message except it does not include the subprocess output.

More info.

error.originalMessage

Type: string | undefined

Original error message. This is the same as error.message excluding the subprocess output and some additional information added by Execa.

More info.

error.cause

Type: unknown | undefined

Underlying error, if there is one. For example, this is set by subprocess.kill(error).

This is usually an Error instance.

More info.

error.code

Type: string | undefined

Node.js-specific error code, when available.

error.timedOut

Type: boolean

Whether the subprocess timed out due to the timeout option.

More info.

error.isCanceled

Type: boolean

Whether the subprocess was canceled using the cancelSignal option.

More info.

error.isGracefullyCanceled

Type: boolean

Whether the subprocess was canceled using both the cancelSignal and the gracefulCancel options.

More info.

error.isMaxBuffer

Type: boolean

Whether the subprocess failed because its output was larger than the maxBuffer option.

More info.

error.isTerminated

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.

More info.

error.isForcefullyTerminated

Type: boolean

Whether the subprocess was terminated by the SIGKILL signal sent by the forceKillAfterDelay option.

More info.

error.exitCode

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.

More info.

error.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.

More info.

error.signalDescription

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.

More info.

Options

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.

options.preferLocal

Type: boolean
Default: true with $, false otherwise

Prefer locally installed binaries when looking for a binary to execute.

More info.

options.localDir

Type: string | URL
Default: cwd option

Preferred path to find locally installed binaries, when using the preferLocal option.

More info.

options.node

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.

More info.

options.nodeOptions

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.

More info.

options.nodePath

Type: string | URL
Default: process.execPath (current Node.js executable)

Path to the Node.js executable.

Requires the node option to be true.

More info.

options.shell

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.

More info.

options.cwd

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.

More info.

options.env

Type: object
Default: process.env

Environment variables.

Unless the extendEnv option is false, the subprocess also uses the current process' environment variables (process.env).

More info.

options.extendEnv

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.

More info.

options.input

Type: string | Uint8Array | stream.Readable

Write some input to the subprocess' stdin.

See also the inputFile and stdin options.

More info.

options.inputFile

Type: string | URL

Use a file as input to the subprocess' stdin.

See also the input and stdin options.

More info.

options.stdin

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.

options.stdout

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.

options.stderr

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.

options.stdio

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.

options.all

Type: boolean
Default: false

Add a subprocess.all stream and a result.all property.

More info.

options.encoding

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 an Uint8Array.
'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.

More info.

options.lines

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.

More info.

options.stripFinalNewline

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.

More info.

options.maxBuffer

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.

More info.

options.buffer

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.

More info.

options.ipc

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.

More info.

options.serialization

Type: 'json' | 'advanced'
Default: 'advanced'

Specify the kind of serialization used for sending messages between subprocesses when using the ipc option.

More info.

options.ipcInput

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.

More info here and there.

options.verbose

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.

More info.

options.reject

Type: boolean
Default: true

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

More info.

options.timeout

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.

More info.

options.cancelSignal

Type: AbortSignal

When the cancelSignal is aborted, terminate the subprocess using a SIGTERM signal.

When aborted, error.isCanceled becomes true.

More info.

options.gracefulCancel

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.

More info.