execa logo
# 📔 API reference This lists all available [methods](#methods) and their [options](#options-1). This also describes the properties of the [subprocess](#subprocess), [result](#result) and [error](#execaerror) they return. ## Methods ### execa(file, arguments?, options?) `file`: `string | URL`\ `arguments`: `string[]`\ `options`: [`Options`](#options-1)\ _Returns_: [`ResultPromise`](#return-value) Executes a command using `file ...arguments`. More info on the [syntax](execution.md#array-syntax) and [escaping](escaping.md#array-syntax). ### $(file, arguments?, options?) `file`: `string | URL`\ `arguments`: `string[]`\ `options`: [`Options`](#options-1)\ _Returns_: [`ResultPromise`](#return-value) Same as [`execa()`](#execafile-arguments-options) but using [script-friendly default options](scripts.md#script-files). This is the preferred method when executing multiple commands in a script file. [More info.](scripts.md) ### execaNode(scriptPath, arguments?, options?) `scriptPath`: `string | URL`\ `arguments`: `string[]`\ `options`: [`Options`](#options-1)\ _Returns_: [`ResultPromise`](#return-value) Same as [`execa()`](#execafile-arguments-options) but using the [`node: true`](#optionsnode) option. Executes a Node.js file using `node scriptPath ...arguments`. This is the preferred method when executing Node.js files. [More info.](node.md) ### execaSync(file, arguments?, options?) ### $.sync(file, arguments?, options?) ### $.s(file, arguments?, options?) `file`: `string | URL`\ `arguments`: `string[]`\ `options`: [`SyncOptions`](#options-1)\ _Returns_: [`SyncResult`](#return-value) Same as [`execa()`](#execafile-arguments-options) and [`$`](#file-arguments-options) but synchronous. Returns a subprocess [`result`](#result) or throws an [`error`](#execasyncerror). The [`subprocess`](#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.](execution.md#synchronous-execution) ### execa\`command\` ### $\`command\` ### execaNode\`command\` ### execaSync\`command\` ### $.sync\`command\` ### $.s\`command\` `command`: `string`\ _Returns_: [`ResultPromise`](#return-value), [`SyncResult`](#return-value) Same as [`execa()`](#execafile-arguments-options), [`$()`](#file-arguments-options), [`execaNode()`](#execanodescriptpath-arguments-options) and [`execaSync()`](#execasyncfile-arguments-options) but using a [template string](execution.md#template-string-syntax). `command` includes both the `file` and its `arguments`. More info on the [syntax](execution.md#template-string-syntax) and [escaping](escaping.md#template-string-syntax). ### execa(options)\`command\` ### $(options)\`command\` ### execaNode(options)\`command\` ### execaSync(options)\`command\` ### $.sync(options)\`command\` ### $.s(options)\`command\` `command`: `string`\ `options`: [`Options`](#options-1), [`SyncOptions`](#options-1)\ _Returns_: [`ResultPromise`](#return-value), [`SyncResult`](#return-value) Same as [```execa`command` ```](#execacommand) but with [options](#options-1). [More info.](execution.md#template-string-syntax) ### execa(options) ### $(options) ### execaNode(options) ### execaSync(options) ### $.sync(options) ### $.s(options) `options`: [`Options`](#options-1), [`SyncOptions`](#options-1)\ _Returns_: [`ExecaMethod`](#execafile-arguments-options), [`ExecaScriptMethod`](#file-arguments-options), [`ExecaNodeMethod`](#execanodescriptpath-arguments-options), [`ExecaSyncMethod`](#execasyncfile-arguments-options), [`ExecaScriptSyncMethod`](#syncfile-arguments-options) Returns a new instance of those methods but with different default [`options`](#options-1). Consecutive calls are merged to previous ones. [More info.](execution.md#globalshared-options) ### 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.](escaping.md#user-defined-input) ### sendMessage(message, sendMessageOptions?) `message`: [`Message`](ipc.md#message-type)\ `sendMessageOptions`: [`SendMessageOptions`](#sendmessageoptions)\ _Returns_: `Promise` Send a `message` to the parent process. This requires the [`ipc`](#optionsipc) option to be `true`. The [type](ipc.md#message-type) of `message` depends on the [`serialization`](#optionsserialization) option. [More info.](ipc.md#exchanging-messages) #### sendMessageOptions _Type_: `object` #### sendMessageOptions.strict _Type_: `boolean`\ _Default_: `false` Throw when the other process is not receiving or listening to messages. [More info.](ipc.md#ensure-messages-are-received) ### getOneMessage(getOneMessageOptions?) `getOneMessageOptions`: [`GetOneMessageOptions`](#getonemessageoptions)\ _Returns_: [`Promise`](ipc.md#message-type) Receive a single `message` from the parent process. This requires the [`ipc`](#optionsipc) option to be `true`. The [type](ipc.md#message-type) of `message` depends on the [`serialization`](#optionsserialization) option. [More info.](ipc.md#exchanging-messages) #### getOneMessageOptions _Type_: `object` #### getOneMessageOptions.filter _Type_: [`(Message) => boolean`](ipc.md#message-type) Ignore any `message` that returns `false`. [More info.](ipc.md#filter-messages) #### getOneMessageOptions.reference _Type_: `boolean`\ _Default_: `true` Keep the subprocess alive while `getOneMessage()` is waiting. [More info.](ipc.md#keeping-the-subprocess-alive) ### getEachMessage(getEachMessageOptions?) `getEachMessageOptions`: [`GetEachMessageOptions`](#geteachmessageoptions)\ _Returns_: [`AsyncIterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) Iterate over each `message` from the parent process. This requires the [`ipc`](#optionsipc) option to be `true`. The [type](ipc.md#message-type) of `message` depends on the [`serialization`](#optionsserialization) option. [More info.](ipc.md#listening-to-messages) #### getEachMessageOptions _Type_: `object` #### getEachMessageOptions.reference _Type_: `boolean`\ _Default_: `true` Keep the subprocess alive while `getEachMessage()` is waiting. [More info.](ipc.md#keeping-the-subprocess-alive) ### getCancelSignal() _Returns_: [`Promise`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) Retrieves the [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) shared by the [`cancelSignal`](#optionscancelsignal) option. This can only be called inside a subprocess. This requires the [`gracefulCancel`](#optionsgracefulcancel) option to be `true`. [More info.](termination.md#graceful-termination) ## Return value _TypeScript:_ [`ResultPromise`](typescript.md)\ _Type:_ `Subprocess` The return value of all [asynchronous methods](#methods) is both: - the [subprocess](#subprocess). - a `Promise` either resolving with its successful [`result`](#result), or rejecting with its [`error`](#execaerror). [More info.](execution.md#subprocess) ## Subprocess _TypeScript:_ [`Subprocess`](typescript.md) Promise with the following Execa-specific methods and properties. The underlying Node.js [`ChildProcess`](https://nodejs.org/api/child_process.html#class-childprocess) instance is available as [`subprocess.nodeChildProcess`](#subprocessnodechildprocess). This is an escape hatch for Node.js-specific APIs that Execa does not document, such as `.on()`, `.send()`, `.disconnect()`, `.ref()` and `.unref()`. ### subprocess\[Symbol.asyncIterator\]() _Returns_: [`AsyncIterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) Subprocesses are [async iterables](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Symbol/asyncIterator). They iterate over each output line. [More info.](lines.md#progressive-splitting) ### subprocess.iterable(readableOptions?) `readableOptions`: [`ReadableOptions`](#readableoptions)\ _Returns_: [`AsyncIterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) Same as [`subprocess[Symbol.asyncIterator]`](#subprocesssymbolasynciterator) except [options](#readableoptions) can be provided. [More info.](lines.md#progressive-splitting) ### subprocess.pipe(file, arguments?, options?) `file`: `string | URL`\ `arguments`: `string[]`\ `options`: [`Options`](#options-1) and [`PipeOptions`](#pipeoptions)\ _Returns_: [`Promise`](#result) [Pipe](https://nodejs.org/api/stream.html#readablepipedestination-options) the subprocess' [`stdout`](#subprocessstdout) to a second Execa subprocess' [`stdin`](#subprocessstdin). This resolves with that second subprocess' [result](#result). If either subprocess is rejected, this is rejected with that subprocess' [error](#execaerror) instead. This follows the same syntax as [`execa(file, arguments?, options?)`](#execafile-arguments-options) except both [regular options](#options-1) and [pipe-specific options](#pipeoptions) can be specified. Like a subprocess, the return value can be [iterated](lines.md#progressive-splitting), [converted to a stream](streams.md#converting-a-subprocess-to-a-stream), or used for [IPC](ipc.md) with the destination subprocess. [More info.](pipe.md#array-syntax) ### subprocess.pipe\`command\` ### subprocess.pipe(options)\`command\` `command`: `string`\ `options`: [`Options`](#options-1) and [`PipeOptions`](#pipeoptions)\ _Returns_: [`Promise`](#result) Like [`subprocess.pipe(file, arguments?, options?)`](#subprocesspipefile-arguments-options) but using a [`command` template string](execution.md#template-string-syntax) instead. This follows the same syntax as `execa` [template strings](execution.md#template-string-syntax). [More info.](pipe.md#template-string-syntax) ### subprocess.pipe(secondSubprocess, pipeOptions?) `secondSubprocess`: [`ResultPromise`](#return-value)\ `pipeOptions`: [`PipeOptions`](#pipeoptions)\ _Returns_: [`Promise`](#result) Like [`subprocess.pipe(file, arguments?, options?)`](#subprocesspipefile-arguments-options) but using the [return value](#return-value) of another [`execa()`](#execafile-arguments-options) call instead. [More info.](pipe.md#advanced-syntax) #### pipeOptions _Type:_ `object` #### pipeOptions.from _Type:_ `"stdout" | "stderr" | "all" | "fd3" | "fd4" | ...`\ _Default:_ `"stdout"` Which stream to pipe from the source subprocess. A [file descriptor](https://en.wikipedia.org/wiki/File_descriptor) like `"fd3"` can also be passed. `"all"` pipes both [`stdout`](#subprocessstdout) and [`stderr`](#subprocessstderr). This requires the [`all`](#optionsall) option to be `true`. [More info.](pipe.md#source-file-descriptor) #### pipeOptions.to _Type:_ `"stdin" | "fd3" | "fd4" | ...`\ _Default:_ `"stdin"` Which [stream](#subprocessstdin) to pipe to the destination subprocess. A [file descriptor](https://en.wikipedia.org/wiki/File_descriptor) like `"fd3"` can also be passed. [More info.](pipe.md#destination-file-descriptor) #### pipeOptions.unpipeSignal _Type:_ [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) Unpipe the subprocess when the signal aborts. [More info.](pipe.md#unpipe) ### subprocess.kill(signal, error?) ### subprocess.kill(error?) `signal`: `string | number`\ `error`: `Error`\ _Returns_: `boolean` Sends a [signal](https://nodejs.org/api/os.html#signal-constants) to the subprocess. The default signal is the [`killSignal`](#optionskillsignal) option. `killSignal` defaults to `SIGTERM`, which [terminates](#erroristerminated) 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`](#errorcause). The subprocess is then terminated with the default signal. This does not emit the [`error` event](https://nodejs.org/api/child_process.html#event-error). [More info.](termination.md) ### subprocess.pid _Type:_ `number | undefined` Process identifier ([PID](https://en.wikipedia.org/wiki/Process_identifier)). This is `undefined` if the subprocess failed to spawn. [More info.](termination.md#inter-process-termination) ### subprocess.nodeChildProcess _Type:_ [`ChildProcess`](https://nodejs.org/api/child_process.html#class-childprocess) Underlying Node.js child process instance. This is intended as an escape hatch for Node.js-specific APIs that Execa does not document. ### subprocess.sendMessage(message, sendMessageOptions) `message`: [`Message`](ipc.md#message-type)\ `sendMessageOptions`: [`SendMessageOptions`](#sendmessageoptions)\ _Returns_: `Promise` Send a `message` to the subprocess. This requires the [`ipc`](#optionsipc) option to be `true`. The [type](ipc.md#message-type) of `message` depends on the [`serialization`](#optionsserialization) option. [More info.](ipc.md#exchanging-messages) ### subprocess.getOneMessage(getOneMessageOptions?) `getOneMessageOptions`: [`GetOneMessageOptions`](#getonemessageoptions)\ _Returns_: [`Promise`](ipc.md#message-type) Receive a single `message` from the subprocess. This requires the [`ipc`](#optionsipc) option to be `true`. The [type](ipc.md#message-type) of `message` depends on the [`serialization`](#optionsserialization) option. [More info.](ipc.md#exchanging-messages) ### subprocess.getEachMessage(getEachMessageOptions?) `getEachMessageOptions`: [`GetEachMessageOptions`](#geteachmessageoptions)\ _Returns_: [`AsyncIterable`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#the_async_iterator_and_async_iterable_protocols) Iterate over each `message` from the subprocess. This requires the [`ipc`](#optionsipc) option to be `true`. The [type](ipc.md#message-type) of `message` depends on the [`serialization`](#optionsserialization) option. [More info.](ipc.md#listening-to-messages) ### subprocess.stdin _Type:_ [`Writable | null`](https://nodejs.org/api/stream.html#class-streamwritable) The subprocess [`stdin`](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)) as a stream. This is `null` if the [`stdin`](#optionsstdin) option is set to [`'inherit'`](input.md#terminal-input), [`'ignore'`](input.md#ignore-input), [`Readable`](streams.md#input) or [`integer`](input.md#terminal-input). [More info.](streams.md#manual-streaming) ### subprocess.stdout _Type:_ [`Readable | null`](https://nodejs.org/api/stream.html#class-streamreadable) The subprocess [`stdout`](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)) as a stream. This is `null` if the [`stdout`](#optionsstdout) option is set to [`'inherit'`](output.md#terminal-output), [`'ignore'`](output.md#ignore-output), [`Writable`](streams.md#output) or [`integer`](output.md#terminal-output), or if the [`buffer`](#optionsbuffer) option is `false`. [More info.](streams.md#manual-streaming) ### subprocess.stderr _Type:_ [`Readable | null`](https://nodejs.org/api/stream.html#class-streamreadable) The subprocess [`stderr`](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)) as a stream. This is `null` if the [`stderr`](#optionsstdout) option is set to [`'inherit'`](output.md#terminal-output), [`'ignore'`](output.md#ignore-output), [`Writable`](streams.md#output) or [`integer`](output.md#terminal-output), or if the [`buffer`](#optionsbuffer) option is `false`. [More info.](streams.md#manual-streaming) ### subprocess.all _Type:_ [`Readable | undefined`](https://nodejs.org/api/stream.html#class-streamreadable) Stream combining/interleaving [`subprocess.stdout`](#subprocessstdout) and [`subprocess.stderr`](#subprocessstderr). This requires the [`all`](#optionsall) option to be `true`. This is `undefined` if [`stdout`](#optionsstdout) and [`stderr`](#optionsstderr) options are set to [`'inherit'`](output.md#terminal-output), [`'ignore'`](output.md#ignore-output), [`Writable`](streams.md#output) or [`integer`](output.md#terminal-output), or if the [`buffer`](#optionsbuffer) option is `false`. More info on [interleaving](output.md#interleaved-output) and [streaming](streams.md#manual-streaming). ### subprocess.stdio _Type:_ [`[Writable | null, Readable | null, Readable | null, ...Array]`](https://nodejs.org/api/stream.html#class-streamreadable) The subprocess [`stdin`](#subprocessstdin), [`stdout`](#subprocessstdout), [`stderr`](#subprocessstderr) and [other files descriptors](#optionsstdio) as an array of streams. Each array item is `null` if the corresponding [`stdin`](#optionsstdin), [`stdout`](#optionsstdout), [`stderr`](#optionsstderr) or [`stdio`](#optionsstdio) option is set to [`'inherit'`](output.md#terminal-output), [`'ignore'`](output.md#ignore-output), [`Stream`](streams.md#output) or [`integer`](output.md#terminal-output), or if the [`buffer`](#optionsbuffer) option is `false`. [More info.](streams.md#manual-streaming) ### subprocess.readable(readableOptions?) `readableOptions`: [`ReadableOptions`](#readableoptions)\ _Returns_: [`Readable`](https://nodejs.org/api/stream.html#class-streamreadable) Node.js stream Converts the subprocess to a readable stream. [More info.](streams.md#converting-a-subprocess-to-a-stream) #### readableOptions _Type:_ `object` #### readableOptions.from _Type:_ `"stdout" | "stderr" | "all" | "fd3" | "fd4" | ...`\ _Default:_ `"stdout"` Which stream to read from the subprocess. A [file descriptor](https://en.wikipedia.org/wiki/File_descriptor) like `"fd3"` can also be passed. `"all"` reads both [`stdout`](#subprocessstdout) and [`stderr`](#subprocessstderr). This requires the [`all`](#optionsall) option to be `true`. [More info.](streams.md#different-file-descriptor) #### readableOptions.binary _Type:_ `boolean`\ _Default:_ `false` with [`subprocess.iterable()`](#subprocessiterablereadableoptions), `true` with [`subprocess.readable()`](#subprocessreadablereadableoptions)/[`subprocess.duplex()`](#subprocessduplexduplexoptions) If `false`, iterates over lines. Each line is a string. If `true`, iterates over arbitrary chunks of data. Each line is an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) (with [`subprocess.iterable()`](#subprocessiterablereadableoptions)) or a [`Buffer`](https://nodejs.org/api/buffer.html#class-buffer) (with [`subprocess.readable()`](#subprocessreadablereadableoptions)/[`subprocess.duplex()`](#subprocessduplexduplexoptions)). This is always `true` when the [`encoding`](#optionsencoding) option is binary. More info for [iterables](binary.md#iterable) and [streams](binary.md#streams). #### readableOptions.preserveNewlines _Type:_ `boolean`\ _Default:_ `false` with [`subprocess.iterable()`](#subprocessiterablereadableoptions), `true` with [`subprocess.readable()`](#subprocessreadablereadableoptions)/[`subprocess.duplex()`](#subprocessduplexduplexoptions) If both this option and the [`binary`](#readableoptionsbinary) option is `false`, [newlines](https://en.wikipedia.org/wiki/Newline) are stripped from each line. [More info.](lines.md#iterable) ### subprocess.writable(writableOptions?) `writableOptions`: [`WritableOptions`](#writableoptions)\ _Returns_: [`Writable`](https://nodejs.org/api/stream.html#class-streamwritable) Node.js stream Converts the subprocess to a writable stream. [More info.](streams.md#converting-a-subprocess-to-a-stream) #### writableOptions _Type:_ `object` #### writableOptions.to _Type:_ `"stdin" | "fd3" | "fd4" | ...`\ _Default:_ `"stdin"` Which [stream](#subprocessstdin) to write to the subprocess. A [file descriptor](https://en.wikipedia.org/wiki/File_descriptor) like `"fd3"` can also be passed. [More info.](streams.md#different-file-descriptor) ### subprocess.duplex(duplexOptions?) `duplexOptions`: [`ReadableOptions | WritableOptions`](#readableoptions)\ _Returns_: [`Duplex`](https://nodejs.org/api/stream.html#class-streamduplex) Node.js stream Converts the subprocess to a duplex stream. [More info.](streams.md#converting-a-subprocess-to-a-stream) ### subprocess.readableStream(readableOptions?) `readableOptions`: [`ReadableOptions`](#readableoptions)\ _Returns_: [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream) web stream Converts the subprocess to a readable web stream. [More info.](streams.md#converting-a-subprocess-to-a-web-stream) ### subprocess.writableStream(writableOptions?) `writableOptions`: [`WritableOptions`](#writableoptions)\ _Returns_: [`WritableStream`](https://developer.mozilla.org/en-US/docs/Web/API/WritableStream) web stream Converts the subprocess to a writable web stream. [More info.](streams.md#converting-a-subprocess-to-a-web-stream) ### subprocess.transformStream(duplexOptions?) `duplexOptions`: [`ReadableOptions | WritableOptions`](#readableoptions)\ _Returns_: [`{readable: ReadableStream, writable: WritableStream}`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) Converts the subprocess to a [`{readable, writable}`](https://developer.mozilla.org/en-US/docs/Web/API/TransformStream) pair of web streams. [More info.](streams.md#converting-a-subprocess-to-a-web-stream) ## Result _TypeScript:_ [`Result`](typescript.md) or [`SyncResult`](typescript.md)\ _Type:_ `object` [Result](execution.md#result) of a subprocess successful execution. When the subprocess [fails](errors.md#subprocess-failure), it is rejected with an [`ExecaError`](#execaerror) instead. ### result.stdout _Type:_ `string | Uint8Array | string[] | Uint8Array[] | unknown[] | undefined` The output of the subprocess on [`stdout`](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)). This is `undefined` if the [`stdout`](#optionsstdout) option is set to only [`'inherit'`](output.md#terminal-output), [`'ignore'`](output.md#ignore-output), [`Writable`](streams.md#output) or [`integer`](output.md#terminal-output), or if the [`buffer`](#optionsbuffer) option is `false`. This is an array if the [`lines`](#optionslines) option is `true`, or if the `stdout` option is a [transform in object mode](transform.md#object-mode). [More info.](output.md#stdout-and-stderr) ### result.stderr _Type:_ `string | Uint8Array | string[] | Uint8Array[] | unknown[] | undefined` The output of the subprocess on [`stderr`](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)). This is `undefined` if the [`stderr`](#optionsstderr) option is set to only [`'inherit'`](output.md#terminal-output), [`'ignore'`](output.md#ignore-output), [`Writable`](streams.md#output) or [`integer`](output.md#terminal-output), or if the [`buffer`](#optionsbuffer) option is `false`. This is an array if the [`lines`](#optionslines) option is `true`, or if the `stderr` option is a [transform in object mode](transform.md#object-mode). [More info.](output.md#stdout-and-stderr) ### result.all _Type:_ `string | Uint8Array | string[] | Uint8Array[] | unknown[] | undefined` The output of the subprocess with [`result.stdout`](#resultstdout) and [`result.stderr`](#resultstderr) interleaved. This requires the [`all`](#optionsall) option to be `true`. This is `undefined` if both [`stdout`](#optionsstdout) and [`stderr`](#optionsstderr) options are set to only [`'inherit'`](output.md#terminal-output), [`'ignore'`](output.md#ignore-output), [`Writable`](streams.md#output) or [`integer`](output.md#terminal-output), or if the [`buffer`](#optionsbuffer) option is `false`. This is an array if the [`lines`](#optionslines) option is `true`, or if either the `stdout` or `stderr` option is a [transform in object mode](transform.md#object-mode). [More info.](output.md#interleaved-output) ### result.stdio _Type:_ `Array` The output of the subprocess on [`stdin`](#optionsstdin), [`stdout`](#optionsstdout), [`stderr`](#optionsstderr) and [other file descriptors](#optionsstdio). Items are `undefined` when their corresponding [`stdio`](#optionsstdio) option is set to [`'inherit'`](output.md#terminal-output), [`'ignore'`](output.md#ignore-output), [`Writable`](streams.md#output) or [`integer`](output.md#terminal-output), or if the [`buffer`](#optionsbuffer) option is `false`. Items are arrays when their corresponding `stdio` option is a [transform in object mode](transform.md#object-mode). [More info.](output.md#additional-file-descriptors) ### result.ipcOutput _Type_: [`Message[]`](ipc.md#message-type) All the messages [sent by the subprocess](#sendmessagemessage-sendmessageoptions) to the current process. This is empty unless the [`ipc`](#optionsipc) option is `true`. Also, this is empty if the [`buffer`](#optionsbuffer) option is `false`. [More info.](ipc.md#retrieve-all-messages) ### result.pipedFrom _Type:_ [`Array`](#result) [Results](#result) of the other subprocesses that were piped into this subprocess. This array is initially empty and is populated each time the [`subprocess.pipe()`](#subprocesspipefile-arguments-options) method resolves. [More info.](pipe.md#result) ### result.command _Type:_ `string` The file and [arguments](input.md#command-arguments) that were run. [More info.](debugging.md#command) ### result.escapedCommand _Type:_ `string` Same as [`command`](#resultcommand) but escaped. [More info.](debugging.md#command) ### result.cwd _Type:_ `string` The [current directory](#optionscwd) in which the command was run. [More info.](environment.md#current-directory) ### result.durationMs _Type:_ `number` Duration of the subprocess, in milliseconds. [More info.](debugging.md#duration) ### result.failed _Type:_ `boolean` Whether the subprocess failed to run. When this is `true`, the result is an [`ExecaError`](#execaerror) instance with additional error-related properties. [More info.](errors.md#subprocess-failure) ## ExecaError ## ExecaSyncError _Type:_ `Error` Result of a subprocess [failed execution](errors.md#subprocess-failure). This error is thrown as an exception. If the [`reject`](#optionsreject) option is false, it is returned instead. This has the same shape as [successful results](#result), with the following additional properties. [More info.](errors.md) ### error.message _Type:_ `string` Error message when the subprocess [failed](errors.md#subprocess-failure) to run. [More info.](errors.md#error-message) ### error.shortMessage _Type:_ `string` This is the same as [`error.message`](#errormessage) except it does not include the subprocess [output](output.md). [More info.](errors.md#error-message) ### error.originalMessage _Type:_ `string | undefined` Original error message. This is the same as [`error.message`](#errormessage) excluding the subprocess [output](output.md) and some additional information added by Execa. [More info.](errors.md#error-message) ### error.cause _Type:_ `unknown | undefined` Underlying error, if there is one. For example, this is set by [`subprocess.kill(error)`](#subprocesskillerror). This is usually an `Error` instance. [More info.](termination.md#error-message-and-stack-trace) ### error.code _Type:_ `string | undefined` Node.js-specific [error code](https://nodejs.org/api/errors.html#errorcode), when available. ### error.timedOut _Type:_ `boolean` Whether the subprocess timed out due to the [`timeout`](#optionstimeout) option. [More info.](termination.md#timeout) ### error.isCanceled _Type:_ `boolean` Whether the subprocess was canceled using the [`cancelSignal`](#optionscancelsignal) option. [More info.](termination.md#canceling) ### error.isGracefullyCanceled _Type:_ `boolean` Whether the subprocess was canceled using both the [`cancelSignal`](#optionscancelsignal) and the [`gracefulCancel`](#optionsgracefulcancel) options. [More info.](termination.md#graceful-termination) ### error.isMaxBuffer _Type:_ `boolean` Whether the subprocess failed because its output was larger than the [`maxBuffer`](#optionsmaxbuffer) option. [More info.](output.md#big-output) ### error.isTerminated _Type:_ `boolean` Whether the subprocess was terminated by a [signal](termination.md#signal-termination) (like [`SIGTERM`](termination.md#sigterm)) sent by either: - The current process. - [Another process](termination.md#inter-process-termination). This case is [not supported on Windows](https://nodejs.org/api/process.html#signal-events). [More info.](termination.md#signal-name-and-description) ### error.isForcefullyTerminated _Type:_ `boolean` Whether the subprocess was terminated by the [`SIGKILL`](termination.md#sigkill) signal sent by the [`forceKillAfterDelay`](#optionsforcekillafterdelay) option. [More info.](termination.md#forceful-termination) ### error.exitCode _Type:_ `number | undefined` The numeric [exit code](https://en.wikipedia.org/wiki/Exit_status) of the subprocess that was run. This is `undefined` when the subprocess could not be spawned or was terminated by a [signal](#errorsignal). [More info.](errors.md#exit-code) ### error.signal _Type:_ `string | undefined` The name of the [signal](termination.md#signal-termination) (like [`SIGTERM`](termination.md#sigterm)) that terminated the subprocess, sent by either: - The current process. - [Another process](termination.md#inter-process-termination). This case is [not supported on Windows](https://nodejs.org/api/process.html#signal-events). If a signal terminated the subprocess, this property is defined and included in the [error message](#errormessage). Otherwise it is `undefined`. [More info.](termination.md#signal-name-and-description) ### error.signalDescription _Type:_ `string | undefined` A human-friendly description of the [signal](termination.md#signal-termination) 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.](termination.md#signal-name-and-description) ## Options _TypeScript:_ [`Options`](typescript.md) or [`SyncOptions`](typescript.md)\ _Type:_ `object` This lists all options for [`execa()`](#execafile-arguments-options) and the [other methods](#methods). The following options [can specify different values](output.md#stdoutstderr-specific-options) for [`stdout`](#optionsstdout) and [`stderr`](#optionsstderr): [`verbose`](#optionsverbose), [`lines`](#optionslines), [`stripFinalNewline`](#optionsstripfinalnewline), [`buffer`](#optionsbuffer), [`maxBuffer`](#optionsmaxbuffer). ### options.preferLocal _Type:_ `boolean`\ _Default:_ `true` with [`$`](#file-arguments-options), `false` otherwise Prefer locally installed binaries when looking for a binary to execute. [More info.](environment.md#local-binaries) ### options.localDir _Type:_ `string | URL`\ _Default:_ [`cwd`](#optionscwd) option Preferred path to find locally installed binaries, when using the [`preferLocal`](#optionspreferlocal) option. [More info.](environment.md#local-binaries) ### options.node _Type:_ `boolean`\ _Default:_ `true` with [`execaNode()`](#execanodescriptpath-arguments-options), `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](https://nodejs.org/api/cli.html#options) and version. This can be overridden using the [`nodeOptions`](#optionsnodeoptions) and [`nodePath`](#optionsnodepath) options. [More info.](node.md) ### options.nodeOptions _Type:_ `string[]`\ _Default:_ [`process.execArgv`](https://nodejs.org/api/process.html#process_process_execargv) (current Node.js CLI flags) List of [CLI flags](https://nodejs.org/api/cli.html#cli_options) passed to the [Node.js executable](#optionsnodepath). Requires the [`node`](#optionsnode) option to be `true`. [More info.](node.md#nodejs-cli-flags) ### options.nodePath _Type:_ `string | URL`\ _Default:_ [`process.execPath`](https://nodejs.org/api/process.html#process_process_execpath) (current Node.js executable) Path to the Node.js executable. Requires the [`node`](#optionsnode) option to be `true`. [More info.](node.md#nodejs-version) ### options.shell _Type:_ `boolean | string | URL`\ _Default:_ `false` If `true`, runs the command inside of a [shell](https://en.wikipedia.org/wiki/Shell_(computing)). Uses [`/bin/sh`](https://en.wikipedia.org/wiki/Unix_shell) on UNIX and [`cmd.exe`](https://en.wikipedia.org/wiki/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](shell.md#avoiding-shells) using this option. [More info.](shell.md) ### options.cwd _Type:_ `string | URL`\ _Default:_ `process.cwd()` Current [working directory](https://en.wikipedia.org/wiki/Working_directory) of the subprocess. This is also used to resolve the [`nodePath`](#optionsnodepath) option when it is a relative path. [More info.](environment.md#current-directory) ### options.env _Type:_ `object`\ _Default:_ [`process.env`](https://nodejs.org/api/process.html#processenv) [Environment variables](https://en.wikipedia.org/wiki/Environment_variable). Unless the [`extendEnv`](#optionsextendenv) option is `false`, the subprocess also uses the current process' environment variables ([`process.env`](https://nodejs.org/api/process.html#processenv)). [More info.](input.md#environment-variables) ### options.extendEnv _Type:_ `boolean`\ _Default:_ `true` If `true`, the subprocess uses both the [`env`](#optionsenv) option and the current process' environment variables ([`process.env`](https://nodejs.org/api/process.html#processenv)). If `false`, only the `env` option is used, not `process.env`. [More info.](input.md#environment-variables) ### options.input _Type:_ `string | Uint8Array | stream.Readable` Write some input to the subprocess' [`stdin`](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)). See also the [`inputFile`](#optionsinputfile) and [`stdin`](#optionsstdin) options. [More info.](input.md#string-input) ### options.inputFile _Type:_ `string | URL` Use a file as input to the subprocess' [`stdin`](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)). See also the [`input`](#optionsinput) and [`stdin`](#optionsstdin) options. [More info.](input.md#file-input) ### options.stdin _TypeScript:_ [`StdinOption`](typescript.md) or [`StdinSyncOption`](typescript.md)\ _Type:_ `string | number | stream.Readable | ReadableStream | TransformStream | URL | {file: string} | Uint8Array | Iterable | AsyncIterable | GeneratorFunction | AsyncGeneratorFunction | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream}` (or a tuple of those types)\ _Default:_ `'inherit'` with [`$`](#file-arguments-options), `'pipe'` otherwise How to setup the subprocess' [standard input](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)). This can be [`'pipe'`](streams.md#manual-streaming), [`'overlapped'`](windows.md#asynchronous-io), [`'ignore`](input.md#ignore-input), [`'inherit'`](input.md#terminal-input), a [file descriptor integer](input.md#terminal-input), a [Node.js `Readable` stream](streams.md#input), a web [`ReadableStream`](streams.md#web-streams), a [`{ file: 'path' }` object](input.md#file-input), a [file URL](input.md#file-input), an [`Iterable`](streams.md#iterables-as-input) (including an [array of strings](input.md#string-input)), an [`AsyncIterable`](streams.md#iterables-as-input), an [`Uint8Array`](binary.md#binary-input), a [generator function](transform.md), a [`Duplex`](transform.md#duplextransform-streams) or a web [`TransformStream`](transform.md#duplextransform-streams). This can be an [array of values](output.md#multiple-targets) such as `['inherit', 'pipe']` or `[fileUrl, 'pipe']`. More info on [available values](input.md), [streaming](streams.md) and [transforms](transform.md). ### options.stdout _TypeScript:_ [`StdoutStderrOption`](typescript.md) or [`StdoutStderrSyncOption`](typescript.md)\ _Type:_ `string | number | stream.Writable | WritableStream | TransformStream | URL | {file: string} | GeneratorFunction | AsyncGeneratorFunction | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream}` (or a tuple of those types)\ _Default:_ `pipe` How to setup the subprocess' [standard output](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)). This can be [`'pipe'`](output.md#stdout-and-stderr), [`'overlapped'`](windows.md#asynchronous-io), [`'ignore`](output.md#ignore-output), [`'inherit'`](output.md#terminal-output), a [file descriptor integer](output.md#terminal-output), a [Node.js `Writable` stream](streams.md#output), a web [`WritableStream`](streams.md#web-streams), a [`{ file: 'path' }` object](output.md#file-output), a [file URL](output.md#file-output), a [generator function](transform.md), a [`Duplex`](transform.md#duplextransform-streams) or a web [`TransformStream`](transform.md#duplextransform-streams). This can be an [array of values](output.md#multiple-targets) such as `['inherit', 'pipe']` or `[fileUrl, 'pipe']`. More info on [available values](output.md), [streaming](streams.md) and [transforms](transform.md). ### options.stderr _TypeScript:_ [`StdoutStderrOption`](typescript.md) or [`StdoutStderrSyncOption`](typescript.md)\ _Type:_ `string | number | stream.Writable | WritableStream | TransformStream | URL | {file: string} | GeneratorFunction | AsyncGeneratorFunction | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream}` (or a tuple of those types)\ _Default:_ `pipe` How to setup the subprocess' [standard error](https://en.wikipedia.org/wiki/Standard_streams#Standard_input_(stdin)). This can be [`'pipe'`](output.md#stdout-and-stderr), [`'overlapped'`](windows.md#asynchronous-io), [`'ignore`](output.md#ignore-output), [`'inherit'`](output.md#terminal-output), a [file descriptor integer](output.md#terminal-output), a [Node.js `Writable` stream](streams.md#output), a web [`WritableStream`](streams.md#web-streams), a [`{ file: 'path' }` object](output.md#file-output), a [file URL](output.md#file-output), a [generator function](transform.md), a [`Duplex`](transform.md#duplextransform-streams) or a web [`TransformStream`](transform.md#duplextransform-streams). This can be an [array of values](output.md#multiple-targets) such as `['inherit', 'pipe']` or `[fileUrl, 'pipe']`. More info on [available values](output.md), [streaming](streams.md) and [transforms](transform.md). ### options.stdio _TypeScript:_ [`Options['stdio']`](typescript.md) or [`SyncOptions['stdio']`](typescript.md)\ _Type:_ `string | Array | Iterable | Iterable | AsyncIterable | GeneratorFunction | AsyncGeneratorFunction | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream} | {value: 'pipe' | 'inherit' | number | URL | {file: string} | GeneratorFunction | AsyncGeneratorFunction | {transform: GeneratorFunction | AsyncGeneratorFunction | Duplex | TransformStream}; input?: boolean}>` (or a tuple of those types)\ _Default:_ `pipe` Like the [`stdin`](#optionsstdin), [`stdout`](#optionsstdout) and [`stderr`](#optionsstderr) options but for all [file descriptors](https://en.wikipedia.org/wiki/File_descriptor) 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](output.md#shortcut). The array can have more than 3 items, to create [additional file descriptors](output.md#additional-file-descriptors) beyond [`stdin`](#optionsstdin)/[`stdout`](#optionsstdout)/[`stderr`](#optionsstderr). Some values have an ambiguous direction on an additional file descriptor (like `'pipe'`, `'inherit'`, a file or a transform), so they default to output. To use one for [input](input.md#additional-file-descriptors) instead, wrap it as `{value, input: true}`. More info on [available values](output.md), [streaming](streams.md) and [transforms](transform.md). ### options.all _Type:_ `boolean`\ _Default:_ `false` Add a [`subprocess.all`](#subprocessall) stream and a [`result.all`](#resultall) property. [More info.](output.md#interleaved-output) ### options.encoding _Type:_ `'utf8' | 'utf16le' | 'buffer' | 'hex' | 'base64' | 'base64url' | 'latin1' | 'ascii'`\ _Default:_ `'utf8'` If the subprocess outputs text, specifies its character encoding, either [`'utf8'`](https://en.wikipedia.org/wiki/UTF-8) or [`'utf16le'`](https://en.wikipedia.org/wiki/UTF-16). If it outputs binary data instead, this should be either: - `'buffer'`: returns the binary output as an [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array). - [`'hex'`](https://en.wikipedia.org/wiki/Hexadecimal), [`'base64'`](https://en.wikipedia.org/wiki/Base64), [`'base64url'`](https://en.wikipedia.org/wiki/Base64#RFC_4648), [`'latin1'`](https://nodejs.org/api/buffer.html#buffers-and-character-encodings) or [`'ascii'`](https://nodejs.org/api/buffer.html#buffers-and-character-encodings): encodes the binary output as a string. The output is available with [`result.stdout`](#resultstdout), [`result.stderr`](#resultstderr) and [`result.stdio`](#resultstdio). [More info.](binary.md) ### options.lines _Type:_ `boolean`\ _Default:_ `false` Set [`result.stdout`](#resultstdout), [`result.stderr`](#resultstdout), [`result.all`](#resultall) and [`result.stdio`](#resultstdio) as arrays of strings, splitting the subprocess' output into lines. This cannot be used if the [`encoding`](#optionsencoding) option is [binary](binary.md#binary-output). By default, this applies to both `stdout` and `stderr`, but [different values can also be passed](output.md#stdoutstderr-specific-options). [More info.](lines.md#simple-splitting) ### options.stripFinalNewline _Type:_ `boolean`\ _Default:_ `true` Strip the final [newline character](https://en.wikipedia.org/wiki/Newline) from the output. If the [`lines`](#optionslines) 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](output.md#stdoutstderr-specific-options). [More info.](lines.md#newlines) ### options.maxBuffer _Type:_ `number`\ _Default:_ `100_000_000` Largest amount of data allowed on [`stdout`](#resultstdout), [`stderr`](#resultstderr) and [`stdio`](#resultstdio). By default, this applies to both `stdout` and `stderr`, but [different values can also be passed](output.md#stdoutstderr-specific-options). When reached, [`error.isMaxBuffer`](#errorismaxbuffer) becomes `true`. [More info.](output.md#big-output) ### options.buffer _Type:_ `boolean`\ _Default:_ `true` When `buffer` is `false`, the [`result.stdout`](#resultstdout), [`result.stderr`](#resultstderr), [`result.all`](#resultall) and [`result.stdio`](#resultstdio) properties are not set. By default, this applies to both `stdout` and `stderr`, but [different values can also be passed](output.md#stdoutstderr-specific-options). [More info.](output.md#low-memory) ### options.ipc _Type:_ `boolean`\ _Default:_ `true` if the [`node`](#optionsnode), [`ipcInput`](#optionsipcinput) or [`gracefulCancel`](#optionsgracefulcancel) option is set, `false` otherwise Enables exchanging messages with the subprocess using [`subprocess.sendMessage(message)`](#subprocesssendmessagemessage-sendmessageoptions), [`subprocess.getOneMessage()`](#subprocessgetonemessagegetonemessageoptions) and [`subprocess.getEachMessage()`](#subprocessgeteachmessagegeteachmessageoptions). The subprocess must be a Node.js file. [More info.](ipc.md) ### options.serialization _Type:_ `'json' | 'advanced'`\ _Default:_ `'advanced'` Specify the kind of serialization used for sending messages between subprocesses when using the [`ipc`](#optionsipc) option. [More info.](ipc.md#message-type) ### options.ipcInput _Type_: [`Message`](ipc.md#message-type) Sends an IPC message when the subprocess starts. The subprocess must be a [Node.js file](#optionsnode). The value's [type](ipc.md#message-type) depends on the [`serialization`](#optionsserialization) option. More info [here](ipc.md#send-an-initial-message) and [there](input.md#any-input-type). ### options.verbose _Type:_ `'none' | 'short' | 'full' | Function`\ _Default:_ `'none'` If `verbose` is `'short'`, prints the command on [`stderr`](https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr)): its file, arguments, duration and (if it failed) error message. If `verbose` is `'full'` or a function, the command's [`stdout`](https://en.wikipedia.org/wiki/Standard_streams#Standard_output_(stdout)), `stderr` and [IPC messages](ipc.md) are also printed. A [function](#verbose-function) can be passed to customize logging. Please see [this page](debugging.md#custom-logging) for more information. By default, this applies to both `stdout` and `stderr`, but [different values can also be passed](output.md#stdoutstderr-specific-options). [More info.](debugging.md#verbose-mode) ### options.reject _Type:_ `boolean`\ _Default:_ `true` Setting this to `false` resolves the [result's promise](#return-value) with the [error](#execaerror) instead of rejecting it. [More info.](errors.md#preventing-exceptions) ### options.timeout _Type:_ `number`\ _Default:_ `0` If `timeout` is greater than `0`, the subprocess will be [terminated](#optionskillsignal) if it runs for longer than that amount of milliseconds. On timeout, [`error.timedOut`](#errortimedout) becomes `true`. [More info.](termination.md#timeout) ### options.cancelSignal _Type:_ [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) When the `cancelSignal` is [aborted](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort), terminate the subprocess using a `SIGTERM` signal. When aborted, [`error.isCanceled`](#erroriscanceled) becomes `true`. [More info.](termination.md#canceling) ### options.gracefulCancel _Type:_ `boolean`\ _Default:_: `false` When the [`cancelSignal`](#optionscancelsignal) option is [aborted](https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort), do not send any [`SIGTERM`](termination.md#canceling). Instead, abort the [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal) returned by [`getCancelSignal()`](#getcancelsignal). The subprocess should use it to terminate gracefully. The subprocess must be a [Node.js file](#optionsnode). When aborted, [`error.isGracefullyCanceled`](#errorisgracefullycanceled) becomes `true`. [More info.](termination.md#graceful-termination) ### options.forceKillAfterDelay _Type:_ `number | false`\ _Default:_ `5000` If the subprocess is terminated but does not exit, forcefully exit it by sending [`SIGKILL`](https://en.wikipedia.org/wiki/Signal_(IPC)#SIGKILL). When this happens, [`error.isForcefullyTerminated`](#errorisforcefullyterminated) becomes `true`. [More info.](termination.md#forceful-termination) ### options.killSignal _Type:_ `string | number`\ _Default:_ `'SIGTERM'` Default [signal](https://en.wikipedia.org/wiki/Signal_(IPC)) used to terminate the subprocess. This can be either a name (like [`'SIGTERM'`](termination.md#sigterm)) or a number (like `9`). [More info.](termination.md#default-signal) ### options.detached _Type:_ `boolean`\ _Default:_ `false` Run the subprocess independently from the current process. [More info.](environment.md#background-subprocess) ### options.cleanup _Type:_ `boolean`\ _Default:_ `true` Kill the subprocess when the current process exits. [More info.](termination.md#current-process-exit) ### options.killDescendants _Type:_ `boolean`\ _Default:_ `false` When the subprocess is terminated by Execa, also terminate all of its descendant processes, instead of only the subprocess itself. This is useful when the subprocess spawns its own processes, such as when using the [`shell`](#optionsshell) option. On Unix, this spawns the subprocess in its own [process group](https://en.wikipedia.org/wiki/Process_group). On Windows, this uses [`taskkill`](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/taskkill). This is best-effort: descendant processes that create their own process group or session are not terminated. [More info.](termination.md#killing-descendant-processes) ### options.uid _Type:_ `number`\ _Default:_ current user identifier Sets the [user identifier](https://en.wikipedia.org/wiki/User_identifier) of the subprocess. [More info.](windows.md#uid-and-gid) ### options.gid _Type:_ `number`\ _Default:_ current group identifier Sets the [group identifier](https://en.wikipedia.org/wiki/Group_identifier) of the subprocess. [More info.](windows.md#uid-and-gid) ### options.argv0 _Type:_ `string`\ _Default:_ file being executed Value of [`argv[0]`](https://nodejs.org/api/process.html#processargv0) sent to the subprocess. ### options.windowsHide _Type:_ `boolean`\ _Default:_ `true` On Windows, do not create a new console window. [More info.](windows.md#console-window) ### options.windowsVerbatimArguments _Type:_ `boolean`\ _Default:_ `true` if the [`shell`](#optionsshell) option is `true`, `false` otherwise If `false`, escapes the command arguments on Windows. [More info.](windows.md#escaping) ## Verbose function _Type_: `(string, VerboseObject) => string | undefined` Function passed to the [`verbose`](#optionsverbose) option to customize logging. [More info.](debugging.md#custom-logging) ### Verbose object _Type_: `VerboseObject` or `SyncVerboseObject` Subprocess event object, for logging purpose, using the [`verbose`](#optionsverbose) option. #### verboseObject.type _Type_: `string` Event type. This can be: - `'command'`: subprocess start - `'output'`: `stdout`/`stderr` [output](output.md#stdout-and-stderr) - `'ipc'`: IPC [output](ipc.md#retrieve-all-messages) - `'error'`: subprocess [failure](errors.md#subprocess-failure) - `'duration'`: subprocess success or failure #### verboseObject.message _Type_: `string` Depending on [`verboseObject.type`](#verboseobjecttype), this is: - `'command'`: the [`result.escapedCommand`](#resultescapedcommand) - `'output'`: one line from [`result.stdout`](#resultstdout) or [`result.stderr`](#resultstderr) - `'ipc'`: one IPC message from [`result.ipcOutput`](#resultipcoutput) - `'error'`: the [`error.shortMessage`](#errorshortmessage) - `'duration'`: the [`result.durationMs`](#resultdurationms) #### verboseObject.escapedCommand _Type_: `string` The file and [arguments](input.md#command-arguments) that were run. This is the same as [`result.escapedCommand`](#resultescapedcommand). #### verboseObject.options _Type_: [`Options`](#options-1) or [`SyncOptions`](#options-1) The [options](#options-1) passed to the subprocess. #### verboseObject.commandId _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](https://en.wikipedia.org/wiki/Process_identifier) except it has no maximum limit, which means it never repeats. Also, it is usually shorter. #### verboseObject.timestamp _Type_: `Date` Event date/time. #### verboseObject.result _Type_: [`Result`](#result), [`SyncResult`](#result) or `undefined` Subprocess [result](#result). This is `undefined` if [`verboseObject.type`](#verboseobjecttype) is `'command'`, `'output'` or `'ipc'`. #### verboseObject.piped _Type_: `boolean` Whether another subprocess is [piped](pipe.md) into this subprocess. This is `false` when [`result.pipedFrom`](#resultfailed) is empty. ## Transform options A transform or an [array of transforms](transform.md#combining) can be passed to the [`stdin`](#optionsstdin), [`stdout`](#optionsstdout), [`stderr`](#optionsstderr) or [`stdio`](#optionsstdio) option. A transform is either a [generator function](#transformoptionstransform) or a plain object with the following members. [More info.](transform.md) ### transformOptions.transform _Type:_ `GeneratorFunction` | `AsyncGeneratorFunction` Map or [filter](transform.md#filtering) the [input](input.md) or [output](output.md) of the subprocess. More info [here](transform.md#summary) and [there](transform.md#sharing-state). ### transformOptions.final _Type:_ `GeneratorFunction` | `AsyncGeneratorFunction` Create additional lines after the last one. [More info.](transform.md#finalizing) ### transformOptions.binary _Type:_ `boolean`\ _Default:_ `false` If `true`, iterate over arbitrary chunks of `Uint8Array`s instead of line `string`s. [More info.](binary.md#transforms) ### transformOptions.preserveNewlines _Type:_ `boolean`\ _Default:_ `false` If `true`, keep newlines in each `line` argument. Also, this allows multiple `yield`s to produce a single line. [More info.](lines.md#transforms) ### transformOptions.objectMode _Type:_ `boolean`\ _Default:_ `false` If `true`, allow [`transformOptions.transform`](#transformoptionstransform) and [`transformOptions.final`](#transformoptionsfinal) to return any type, not just `string` or `Uint8Array`. [More info.](transform.md#object-mode)
[**Previous**: 🔍 Differences with Bash and zx](bash.md)\ [**Top**: Table of contents](../readme.md#documentation)