• Fix VerboseOption type not being properly exported (#1215) 7891c39

v9.6.0...v9.6.1

• Update dependencies d49104a

v9.5.3...v9.6.0

• Fix Node 24-specific deprecation warning (#1199) 1ac5b91

v9.5.2...v9.5.3

Bug fixes

• Fix escaping newlines inside template strings. Thanks @aarondandy! (#1176)

Bug fixes

• Fix odd characters being printed in verbose mode on Windows (thanks @IIIMADDINIII). (#1167)

Features

• When redirecting stdout or stderr to a file, allow appending instead of overwriting. (#1166)

await execa({stdout: {file: 'output.txt', append: true}})`npm run build`;

Bug fixes

• Fix using process.execPath with Deno. Thanks @w3cj! (#1160)

Features

• We've created a separate package called nano-spawn. It is similar to Execa but with fewer features, for a much smaller package size. More info.

Bug fixes

• Both execaNode() and the preferLocal option modify the PATH environment variable. This release includes some minor improvements to ensure that environment variable remains small (sindresorhus/npm-run-path#20). It also handles a few related edge cases better (sindresorhus/npm-run-path#21).

Documentation

• Small documentation typo fix, thanks @rrthomas! (#1153)

Thanks @holic and @jimhigson for your contributions!

Bugs

• Do not crash when using a custom Node.js binary without ICU support. (#1144)

Bugs (types)

• Fix type of the env option. It was currently failing for Remix or Next.js users. (by @holic) (#1141)

Documentation

• Fix typo in "Inputs" documentation. (by @jimhigson) (#1145)
• Document how to terminate hanging subprocesses. (#1140)
• Document how to add custom logging. (#1131)

Features

• The verbose option can now be a function to customize logging. (#1130)

This release includes a new set of methods to exchange messages between the current process and a Node.js subprocess, also known as "IPC". This allows passing and returning almost any message type to/from a Node.js subprocess. Also, debugging IPC is now much easier.

Moreover, a new gracefulCancel option has also been added to terminate a subprocess gracefully.

For a deeper dive-in, please check and share the release post!

Thanks @iiroj for your contribution, @SimonSiefke and @adymorz for reporting the bugs fixed in this release, and @karlhorky for improving the documentation!

Deprecations

• Passing 'ipc' to the stdio option has been deprecated. It will be removed in the next major release. Instead, the ipc: true option should be used. (#1056)

- await execa('npm', ['run', 'build'], {stdio: ['pipe', 'pipe', 'pipe', 'ipc']});
+ await execa('npm', ['run', 'build'], {ipc: true});

• The execaCommand() method has been deprecated. It will be removed in the next major release. If most cases, the template string syntax should be used instead.

- import {execaCommand} from 'execa';
+ import {execa} from 'execa';

- await execaCommand('npm run build');
+ await execa`npm run build`;

const taskName = 'build';
- await execaCommand(`npm run ${taskName}`);
+ await execa`npm run ${taskName}`;

const commandArguments = ['run', 'task with space'];
await execa`npm ${commandArguments}`;

If the file and/or multiple arguments are supplied as a single string, parseCommandString(command) can split that string into an array. More info. (#1054)

- import {execaCommand} from 'execa';
+ import {execa, parseCommandString} from 'execa';

const commandString = 'npm run task';
- await execaCommand(commandString);
+ const commandArray = parseCommandString(commandString); // ['npm', 'run', 'task']
+ await execa`${commandArray}`;

// Or alternatively:
const [file, ...commandArguments] = commandArray;
await execa(file, commandArguments);

Features

• Add gracefulCancel option and getCancelSignal() method to terminate a subprocess gracefully. error.isGracefullyCanceled was also added. (#1109)
• Add error.isForcefullyTerminated. It is true when the subprocess was terminated by the forceKillAfterDelay option. (#1111)
• New methods to simplify exchanging messages between the current process and the subprocess. More info. (#1059, #1061, #1076, #1077, #1079, #1082, #1083, #1086, #1087, #1088, #1089, #1090, #1091, #1092, #1094, #1095, #1098, #1104, #1107)
  • The current process sends messages with subprocess.sendMessage(message) and receives them with subprocess.getOneMessage(). subprocess.getEachMessage() listens to multiple messages.
  • The subprocess uses sendMessage(message), getOneMessage() and getEachMessage() instead. Those are the same methods, but imported directly from the 'execa' module.
• The ipcInput option sends an IPC message from the current process to the subprocess as it starts. This enables passing almost any input type to a Node.js subprocess. (#1068)
• The result.ipcOutput array contains all the IPC messages sent by the subprocess to the current process. This enables returning almost any output type from a Node.js subprocess. (#1067, #1071, #1075)
• The error message now contains every IPC message sent by the subprocess. (#1067)
• The verbose: 'full' option now logs every IPC message sent by the subprocess, for debugging. More info here and there. (#1063)

Types

• Add ExecaMethod, ExecaNodeMethod and ExecaScriptMethod, ExecaSyncMethod and ExecaScriptSyncMethod types. (#1066)
• Export the Message type, for IPC. (#1059)
• Fix type of forceKillAfterDelay: true option. (#1116)

Bug fixes

• Fix passing a {file} to both the stdin and the stdout or stderr options. (#1058)
• Fix multiple minor problems with the cancelSignal option. (#1108)
• Fix accidental publishing of Vim backup files. (#1074)
• Fix engines.node field in package.json. Supported Node.js version is ^18.19.0 or >=20.5.0. (by @iiroj) (#1101)

Features (types)

• Export TemplateExpression type. (#1049)

Bug fixes (types)

• Do not require using --lib dom for TypeScript users (#1043, #1044)
• Fix type of the reject option (#1046)

Bug fixes (types)

• Fix types not being importable (#1033) 3bdab60
• Fix complexity bug with types (#1037) 6cc519b
• Fix complexity bug with types (#1035) fee011d

This major release brings many important features including:

• Split the output into lines, or progressively iterate over them.
• Transform or filter the input/output using simple functions.
• Print the output to the terminal while still retrieving it programmatically.
• Redirect the input/output from/to a file.
• Advanced piping between multiple subprocesses.
• Improved verbose mode, for debugging.
• More detailed errors, including when terminating subprocesses.
• Enhanced template string syntax.
• Global/shared options.
• Web streams and Transform streams support.
• Convert the subprocess to a stream.
• New documentation with many examples.

Please check the release post for a high-level overview! For the full list of breaking changes, features and bug fixes, please read below.

Thanks @younggglcy, @koshic, @am0o0 and @codesmith-emmy for your help!

One of the maintainers @ehmicky is looking for a remote full-time position. Specialized in Node.js back-ends and CLIs, he led Netlify Build, Plugins and Configuration for 2.5 years. Feel free to contact him on his website or on LinkedIn!

Breaking changes (not types)

• Dropped support for Node.js version <18.19.0 and 20.0.0 - 20.4.0. (834e3726)

• When the encoding option is 'buffer', the output (result.stdout, result.stderr, result.all) is now an Uint8Array instead of a Buffer. For more information, see this blog post. (by @younggglcy) (#586)

const {stdout} = await execa('node', ['file.js'], {encoding: 'buffer'});
console.log(stdout); // This is now an Uint8Array

• Renamed some of the allowed values for the encoding option. (#586, #928)

- await execa('node', ['file.js'], {encoding: null});
+ await execa('node', ['file.js'], {encoding: 'buffer'});

- await execa('node', ['file.js'], {encoding: 'utf-8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});

- await execa('node', ['file.js'], {encoding: 'UTF8'});
+ await execa('node', ['file.js'], {encoding: 'utf8'});

- await execa('node', ['file.js'], {encoding: 'utf-16le'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});

- await execa('node', ['file.js'], {encoding: 'ucs2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});

- await execa('node', ['file.js'], {encoding: 'ucs-2'});
+ await execa('node', ['file.js'], {encoding: 'utf16le'});

- await execa('node', ['file.js'], {encoding: 'binary'});
+ await execa('node', ['file.js'], {encoding: 'latin1'});

• Passing a file path to subprocess.pipeStdout(), subprocess.pipeStderr() and subprocess.pipeAll() has been removed. Instead, a {file: './path'} object should be passed to the stdout or stderr option. (#752)

- await execa('node', ['file.js']).pipeStdout('output.txt');
+ await execa('node', ['file.js'], {stdout: {file: 'output.txt'}});

- await execa('node', ['file.js']).pipeStderr('output.txt');
+ await execa('node', ['file.js'], {stderr: {file: 'output.txt'}});

- await execa('node', ['file.js']).pipeAll('output.txt');
+ await execa('node', ['file.js'], {
+	stdout: {file: 'output.txt'},
+	stderr: {file: 'output.txt'},
+});

• Passing a writable stream to subprocess.pipeStdout(), subprocess.pipeStderr() and subprocess.pipeAll() has been removed. Instead, the stream should be passed to the stdout or stderr option. If the stream does not have a file descriptor, ['pipe', stream] should be passed instead. (#752)

- await execa('node', ['file.js']).pipeStdout(stream);
+ await execa('node', ['file.js'], {stdout: ['pipe', stream]});

- await execa('node', ['file.js']).pipeStderr(stream);
+ await execa('node', ['file.js'], {stderr: ['pipe', stream]});

- await execa('node', ['file.js']).pipeAll(stream);
+ await execa('node', ['file.js'], {
+	stdout: ['pipe', stream],
+	stderr: ['pipe', stream],
+});

• The subprocess.pipeStdout(), subprocess.pipeStderr() and subprocess.pipeAll() methods have been renamed to subprocess.pipe(). The command and its arguments can be passed to subprocess.pipe() directly, without calling execa() a second time. The from piping option can specify 'stdout' (the default value), 'stderr' or 'all'. (#757)

- await execa('node', ['file.js']).pipeStdout(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js']);

- await execa('node', ['file.js']).pipeStderr(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'stderr'});

- await execa('node', ['file.js']).pipeAll(execa('node', ['other.js']));
+ await execa('node', ['file.js']).pipe('node', ['other.js'], {from: 'all'});

• Renamed the signal option to cancelSignal. (#880)

- await execa('node', ['file.js'], {signal: abortController.signal});
+ await execa('node', ['file.js'], {cancelSignal: abortController.signal});

• Renamed error.killed to error.isTerminated. (#625)

try {
	await execa('node', ['file.js']);
} catch (error) {
- if (error.killed) {
+ if (error.isTerminated) {
		// ...
	}
}

• subprocess.cancel() has been removed. Please use either subprocess.kill() or the cancelSignal option instead. (#711)

- subprocess.cancel();
+ subprocess.kill();

• Renamed the forceKillAfterTimeout option to forceKillAfterDelay. Also, it is now passed to execa() instead of subprocess.kill(). (#714, #723)

- const subprocess = execa('node', ['file.js']);
- subprocess.kill('SIGTERM', {forceKillAfterTimeout: 1000});
+ const subprocess = execa('node', ['file.js'], {forceKillAfterDelay: 1000});
+ subprocess.kill('SIGTERM');

• The verbose option is now a string enum instead of a boolean. false has been renamed to 'none' and true has been renamed to 'short'. (#884)

- await execa('node', ['file.js'], {verbose: false});
+ await execa('node', ['file.js'], {verbose: 'none'});

- await execa('node', ['file.js'], {verbose: true});
+ await execa('node', ['file.js'], {verbose: 'short'});

• The execPath option has been renamed to nodePath. It is now a noop unless the node option is true. Also, it now works even if the preferLocal option is false. (#812, #815)

- await execa('node', ['file.js'], {execPath: './path/to/node'});
+ await execa('node', ['file.js'], {nodePath: './path/to/node'});

• The default value for the serialization option is now 'advanced' instead of 'json'. In particular, when calling subprocess.send(object) with an object that contains functions or symbols, those were previously silently removed. Now this will throw an exception. (#905)

- subprocess.send({example: true, getExample() {}});
+ subprocess.send({example: true});

• If subprocess.stdout, subprocess.stderr or subprocess.all is manually piped, the .pipe() call must now happen as soon as subprocess is created. Otherwise, the output at the beginning of the subprocess might be missing. (#658, #747)

const subprocess = execa('node', ['file.js']);
- setTimeout(() => {
	subprocess.stdout.pipe(process.stdout);
- }, 0);

• Signals passed to subprocess.kill() and to the killSignal option cannot be lowercase anymore. (#1025)

- const subprocess = execa('node', ['file.js'], {killSignal: 'sigterm'});
+ const subprocess = execa('node', ['file.js'], {killSignal: 'SIGTERM'});

- subprocess.kill('sigterm');
+ subprocess.kill('SIGTERM');

Features

Execution

• Use the template string syntax with any method (including execa()), as opposed to only $. Conversely, $ can now use the regular array syntax. (#933)
• A command's template string can span multiple lines. (#843)
• Share options between multiple calls, or set global options, by using execa(options). (#933, #965)
• Pass a file URL (as opposed to a file path string) to execa(), execaNode(), the inputFile option, the nodePath option or the shell option. (#630, #631, #632, #635)

Text lines

• Split the output into text lines by using the lines option. (#741, #929, #931, #948, #951, #957)
• Subprocess is now an async iterable, iterating over the output lines while the subprocess is running. (#923)

Piping multiple subprocesses

• Simpler syntax: pass the command directly to subprocess.pipe() without calling execa(). A template string can also be used. (#840, #859, #864)
• Wait for both subprocesses to complete. Error handling has been improved too. (#757, #778, #834, #854)
• Retrieve the result of each subprocess (not only the last one) by using result.pipedFrom and error.pipedFrom. (#834)
• Pipe 1 or many subprocesses to 1 or many subprocesses. (#834)
• Pipe subprocesses using other file descriptors than stdin/stdout/stderr by using the from and to piping options. (#757, #834, #903, #920)
• Cancel piping subprocesses by using the unpipeSignal piping option. (#834, #852)

Input/output

• Pass an array with multiple values to the stdin, stdout and stderr options. For example, stdout: ['inherit', 'pipe'] prints the output to the terminal while still returning it as result.stdout. (#643, #765, #941, #954)
• Redirect the input/output from/to a file by passing a {file: './path'} object or a file URL to the stdin, stdout or stderr option. (#610, #614, #621, #671, #1004)
• Transform or filter the input/output by passing a generator function to the stdin, stdout or stderr option. (#693, #697, #698, #699, #709, #736, #737, #739, #740, #746, #748, #755, #756, #780, #783, #867, #915, #916, #917, #919, #924, #926, #945, #969)
• Provide some binary input by passing an Uint8Array to the input or stdin option. (834e3726, #670, #1029)
• Provide some progressive input by passing a sync/async iterable to the stdin option. (#604, #944)
• Provide multiple inputs by combining the stdin, input and inputFile options. (#666)
• Return other file descriptors than result.stdout and result.stderr by using result.stdio. (#676)
• Specify different values for stdout and stderr with the following options: verbose, lines, stripFinalNewline, maxBuffer, buffer. (#966, #970, #971, #972, #973, #974)

Streams

• Redirect the input/output from/to a web stream by passing a ReadableStream or WritableStream to the stdin, stdout or stderr option. (#615, #619, #645)
• Transform or filter the input/output by passing a Duplex, Node.js Transform or web TransformStream to the stdin, stdout or stderr option. (#937, #938)
• Convert the subprocess to a stream by using subprocess.readable(), subprocess.writable() or subprocess.duplex(). (#912, #922, #958)

Verbose mode

• Print the subprocess' completion, duration and errors with the verbose: 'short' or verbose: 'full' option. (#887, #890)
• Print the subprocess' output with the verbose: 'full' option. (#884, #950, #962, #990)
• Prettier formatting and colors with the verbose option. (#883, #893, #894)

Debugging

• Retrieve the subprocess' duration by using result.durationMs and error.durationMs. (#896)
• Retrieve the subprocess' current directory by using result.cwd. Previously only error.cwd was available. Also, result.cwd and error.cwd are now normalized to absolute file paths. (#803)
• Printing result.escapedCommand in a terminal is now safe. (#875)

Errors

• The ExecaError and ExecaSyncError classes are now exported. (#911)
• Find the subprocess failure's root cause by using error.cause. (#911)
• Know whether the subprocess failed due to the maxBuffer option by using error.isMaxBuffer. (#963)
• Improved error.message: error.stdout and error.stderr are now interleaved if the all option is true. Additional file descriptors are now printed too. Also, the formatting has been improved. (#676, #705, #991, #992)
• Control characters in error.message are now escaped, so they don't result in visual bugs when printed in a terminal. (#879)
• Improved stack trace when an error event is emitted on subprocess.stdout or subprocess.stderr. (#814)

Termination

• Specify an error message or stack trace when terminating a subprocess by passing an error instance to subprocess.kill(). (#811, #836, #1023)
• The forceKillAfterDelay and killSignal options now apply to terminations due not only to subprocess.kill() but also to the cancelSignal, timeout, maxBuffer and cleanup options. (#714, #728)

Node.js files

• Use the nodePath and nodeOptions options with any method, as opposed to only execaNode(), by passing the node: true option. (#804, #812, #815)
• When using execaNode() or the node: true option, the current Node.js version is now inherited deeply. If the subprocess spawns other subprocesses, they will all use the same Node.js version. (#812, #815, #1011)

Synchronous execution

• Use the all and buffer: false options with execaSync(), as opposed to only execa(). (#953, #956)
• Added the $.s alias for $.sync. (#594)

Inter-process communication

• Use the ipc: true option, as opposed to the more verbose stdio: ['pipe', 'pipe', 'pipe', 'ipc'] option. (#794)

Input validation

• Improved the validation of the input, timeout, cwd, detached, cancelSignal and encoding options. (#668, #715, #803, #928, #940)
• Improved the validation of the arguments passed to execa() and the other exported methods. (#838, #873, #899)
• Improved the validation of signals passed to subprocess.kill() and to the killSignal option. (#1025)

Bug fixes

• Fixed passing undefined values as options. This now uses the option's default value. (#712)
• Fixed the process crashing when the inputFile option points to a missing file. (#609)
• Fixed the process crashing when the buffer option is false and subprocess.stdout errors. (#729)
• Fixed the process crashing when passing 'overlapped' to the stdout or stderr option with execaSync(). (#949)
• Fixed the process crashing when multiple 'error' events are emitted on the subprocess. (#790)
• Fixed the reject: false option not being used when the subprocess fails to spawn. (#734)
• Fixed some inaccuracies with error.isTerminated. (#625, #719)
  • It is now true when the subprocess fails due to the timeout option.
  • It is now true when calling process.kill(subprocess.pid), except on Windows.
  • It is now false when using non-terminating signals such as subprocess.kill(0).
• Fixed missing error.signal and error.signalDescription when the subprocess is terminated by the cancelSignal option. (#724)
• Fixed a situation where the error returned by an execa() call might be modified by another execa() call. (#796, #806, #911)
• Fixed the verbose option printing the command in the wrong order. (#600)
• Fixed using both the maxBuffer and encoding options. For example, when using encoding: 'hex', maxBuffer will now be measured in hexadecimal characters. Also, error.stdout, error.stderr and error.all were previously not applying the maxBuffer option. (#652, #696)
• Fixed the maxBuffer option not truncating result.stdout and result.stderr when using execaSync(). (#960)
• Fixed empty output when using the buffer: true option (its default value) and iterating over subprocess.stdout or subprocess.stderr. (#908)
• Fixed subprocess.all stream incorrectly being in object mode. (#717)
• Ensured subprocess.stdout and subprocess.stderr are properly flushed when the subprocess fails. (#647)
• Fixed a race condition leading to random behavior with the timeout option. (#727)

Breaking changes (types)

• The minimum supported TypeScript version is now 5.1.6.

• Renamed CommonOptions type to Options (for execa()) and SyncOptions (for execaSync()). (#678, #682)

import type {Options} from 'execa';

- const options: CommonOptions = {timeout: 1000};
+ const options: Options = {timeout: 1000};

• Renamed NodeOptions type to Options. (#804)

import type {Options} from 'execa';

- const options: NodeOptions = {nodeOptions: ['--no-warnings']};
+ const options: Options = {nodeOptions: ['--no-warnings']};

• Renamed KillOptions type to Options. (#714)

import type {Options} from 'execa';

- const options: KillOptions = {forceKillAfterTimeout: 1000};
+ const options: Options = {forceKillAfterDelay: 1000};

• Removed generic parameters from the Options and SyncOptions types. (#681)

import type {Options} from 'execa';

- const options: Options<'utf8'> = {encoding: 'utf8'};
+ const options: Options = {encoding: 'utf8'};

• Renamed ExecaChildProcess type to ResultPromise. This is the type of execa()'s return value, which is both a Promise<Result> and a Subprocess. (#897, #1007, #1009)

import type {ResultPromise, Result} from 'execa';

- const promiseOrSubprocess: ExecaChildProcess = execa('node', ['file.js']);
+ const promiseOrSubprocess: ResultPromise = execa('node', ['file.js']);
const result: Result = await promiseOrSubprocess;
promiseOrSubprocess.kill();

• Renamed ExecaChildPromise type to Subprocess. This is the type of the subprocess instance. (#897, #1007, #1009)

import type {Subprocess} from 'execa';

- const subprocess: ExecaChildPromise = execa('node', ['file.js']);
+ const subprocess: Subprocess = execa('node', ['file.js']);
subprocess.kill();

• Renamed ExecaReturnBase, ExecaReturnValue and ExecaSyncReturnValue type to Result (for execa()) and SyncResult (for execaSync()). (#897, #1009)

import type {Result, SyncResult} from 'execa';

- const result: ExecaReturnBase = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);

- const result: ExecaReturnValue = await execa('node', ['file.js']);
+ const result: Result = await execa('node', ['file.js']);

- const result: ExecaSyncReturnValue = execaSync('node', ['file.js']);
+ const result: SyncResult = execaSync('node', ['file.js']);

• Renamed the type of the stdin option from StdioOption to StdinOption (for execa()) and StdinSyncOption (for execaSync()). (#942, #1008, #1012)

import {execa, type StdinOption} from 'execa';

- const stdin: StdioOption = 'inherit';
+ const stdin: StdinOption = 'inherit';
await execa('node', ['file.js'], {stdin});

• Renamed the type of the stdout and stderr options from StdioOption to StdoutStderrOption (for execa()) and StdoutStderrSyncOption (for execaSync()). (#942, #1008, #1012)

import {execa, type StdoutStderrOption} from 'execa';

- const stdout: StdioOption = 'inherit';
+ const stdout: StdoutStderrOption = 'inherit';
- const stderr: StdioOption = 'inherit';
+ const stderr: StdoutStderrOption = 'inherit';
await execa('node', ['file.js'], {stdout, stderr});

• Renamed the type of the stdio option from StdioOption[] to Options['stdio'] (for execa()) and SyncOptions['stdio'] (for execaSync()). (#942, #1008)

import {execa, type Options} from 'execa';

- const stdio: readonly StdioOption[] = ['inherit', 'pipe', 'pipe'] as const;
+ const stdio: Options['stdio'] = ['inherit', 'pipe', 'pipe'] as const;
await execa('node', ['file.js'], {stdio});

• The optional generic parameter passed to the Result, SyncResult, ExecaError, ExecaSyncError, ResultPromise and Subprocess types is now an Options type. (#681)

import type {Result} from 'execa';

- const result: ExecaReturnValue<Buffer> = await execa('node', ['file.js'], {encoding: 'buffer'});
+ const result: Result<{encoding: 'buffer'}> = await execa('node', ['file.js'], {encoding: 'buffer'});
// Or even better, since it is inferred:
+ const result: Result = await execa('node', ['file.js'], {encoding: 'buffer'});

Improvements (types)

• Stricter types for the stdin, stdout, stderr and stdio options. (#634, #943, #952)
• Stricter types for result.stdout, result.stderr, result.all, subprocess.stdout, subprocess.stderr and subprocess.all. (#681, #684, #687, #689, #833)
• Stricter types for the synchronous methods like execaSync(). (#678, #939)
• Stricter types for the reject option. (#688)
• Stricter types for error.signal and the killSignal option. (#1025)
• Fixed the type of error.exitCode, since that field is sometimes undefined. (#680)
• Refactored and improved the types. (by @koshic) (#583)

Documentation

• Added user guides to let you explore each feature with many examples. (#989, #996, #1015, #1022, #1026)
• Improved the documentation and fixed inaccuracies. (#626, #637, #640, #641, #644, #669, #680, #710, #759, #800, #801, #802, #860, #870, #876, #888, #907, #921, #935, #967, #968, #994, #998, #999, #1000, #1003, #1005, #1006, #1010)
• Fixed the examples for the Script interface. (by @am0o0) (#575)
• Corrected some English grammar mistakes. (by @codesmith-emmy) (#731)

Fixes

• Fix and document support for the {encoding: 'buffer'} option. It is the same as {encoding: null}, but preferred over it. (#572)

https://github.com/sindresorhus/execa/compare/v8.0.0...v8.0.1

Breaking

• Require Node.js 16.17.0 and later (#569)

https://github.com/sindresorhus/execa/compare/v7.2.0...v8.0.0

• Add cwd error property (#565) f57fdec

https://github.com/sindresorhus/execa/compare/v7.1.1...v7.2.0

Features

• Improve error message when $.sync(options)`command` is used instead of $(options).sync`command` (#551)

Bug fixes

• Fix argument concatenation when using $`command argument${value}` (#553)
• Fix default value of the stdin option when using $`command`: it should be inherit (#550)

Features

• Add $ method to write Node.js scripts like zx. For more information, please see this blog post, this section and this page. Thanks @aaronccasanova for this great feature!

import {$} from 'execa';

const branch = await $`git branch --show-current`;
await $`dep deploy --branch=${branch}`;

• Add .pipeStdout(), .pipeStderr() and .pipeAll() methods to redirect stdout/stderr to a file, a stream or another process.

// Similar to `echo unicorns > stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStdout('stdout.txt');

// Similar to `echo unicorns 2> stdout.txt` in Bash
await execa('echo', ['unicorns']).pipeStderr('stderr.txt');

// Similar to `echo unicorns &> stdout.txt` in Bash
await execa('echo', ['unicorns'], {all: true}).pipeAll('all.txt');

• Add inputFile option to use a file as stdin.

// Similar to `cat < stdin.txt` in Bash
const {stdout} = await execa('cat', {inputFile: 'stdin.txt'});
console.log(stdout);
//=> 'unicorns'

• Add verbose option to print each command on stderr before executing it. This can also be enabled by setting the NODE_DEBUG=execa environment variable in the current process.

> node file.js
unicorns
rainbows

> NODE_DEBUG=execa node file.js
[16:50:03.305] echo unicorns
unicorns
[16:50:03.308] echo rainbows
rainbows

Breaking

• Require Node.js 14 and later (#497) a09cbc0

Fixes

• Emit end event on streams when process fails (#518) 30c7a7a
• Fix incorrect execaNode signature in index.d.ts (#506) 1f7677c

https://github.com/sindresorhus/execa/compare/v6.1.0...v7.0.0

• Support AbortController (#490) c6e791a
• Allow cwd and localDir options to be URLs (#492) 93ab929

https://github.com/sindresorhus/execa/compare/v6.0.0...v6.1.0

Breaking

• Require Node.js 12.20 (#478) 7707880
• This package is now pure ESM. Please read this.
• Moved from a default export to named exports.
  • require('execa') → import {execa} from 'execa'
  • require('execa').sync → import {execaSync} from 'execa'
  • require('execa').command → import {execaCommand} from 'execa'
  • require('execa').commandSync → import {execaCommandSync} from 'execa'
  • require('execa').node → import {execaNode} from 'execa'

https://github.com/sindresorhus/execa/compare/v5.1.1...v6.0.0

• Fix error message when user passes a single array argument (#468) 2b9c0e1

https://github.com/sindresorhus/execa/compare/v5.1.0...v5.1.1

• Add .escapedCommand property to the results (#466) 712bafc

https://github.com/sindresorhus/execa/compare/v5.0.1...v5.1.0

• Fix timeout option validation (#463) 427c5c2

https://github.com/sindresorhus/execa/compare/v5.0.0...v5.0.1

Breaking

• Remove faulty emulated ENOENT error on Windows (#447) bdbd975 This is only a breaking change if you depend on the exact error message.

Improvements

• Upgrade dependencies 5d64878

https://github.com/sindresorhus/execa/compare/v4.1.0...v5.0.0

• Remove --inspect & --inspect-brk from execArgv (#435) 8fd3f64

https://github.com/sindresorhus/execa/compare/v4.0.3...v4.1.0

• Fix use of floating number for the timeout and forceKillAfterTimeout options (#431) 9a157b3

https://github.com/sindresorhus/execa/compare/v4.0.2...v4.0.3

Bug fixes

• Fix with third-party promises (like bluebird) not working (#427)

Bug fixes

• Fix checking for Error instances (#423)

Breaking changes

• Require Node.js 10 (5a9c76f)
• Add stderr and stdout to error.message. A new property error.shortMessage is now available to retrieve the error message without stderr nor stdout (#397)

Bug fixes

• Fix childProcess.kill() not working with Electron (#400)

Features

• Add serialization option. That option was added to child_process methods in Node.js 13.2.0. (#392)

Features

• Allow setting the windowsHide option (#388). The option still defaults to true. However previously it could not be set to false.

Documentation

• Add tip on how to retry Execa on failure (#386).
• Improve examples (#385)

Thanks @justsml for helping improving the documentation!

Features

• Add error.signalDescription which is a human-friendly description of the signal that terminated the child process (if one did). That description is included in error messages as well. (#378)

Features

• Add execPath option which allows changing the path to the Node.js executable to use in child processes. (#377)

Breaking changes

• When the buffer option is false and stdout and stderr are piped, the promise returned by execa() will resolve only after those streams are fully read. This also applies to the all property if the all option is true. This concerns you only if you've explicitly set the buffer option to false. (#353)
• The all property is now undefined unless the all option is set to true. (#353)
• error.exitCodeName has been removed. (#375)
• Fix error.exitCode. Its value was previously based on error.errno which is incorrect. (#375)

Features

• Do not remove error.code property when it is defined (#375)
• Improve error messages (#375)
• Add error.originalMessage property (#373)

Bug fixes

• Fix errors being thrown when detached: true or cleanup: false is used (#360)
• Make execa compatible with Node.js 13.0.0-pre (#370)

Dependencies

• Upgrade npm-run-path from 3.0.0 to 4.0.0 (#376)
• Upgrade cross-spawn to 7.0.0 (#367)

Documentation

• Document the reasons why the returned promise might fail (#364)

Features

• Add error.originalMessage property (#373)

Documentation

• Document the reasons why the returned promise might fail (#364)

Dependencies

• Upgrade cross-spawn to 7.0.0 (#367)

Bug fixes

• Make execa compatible with Node.js 13.0.0-pre (#370) d268fd1

https://github.com/sindresorhus/execa/compare/v2.0.4...v2.0.5

Bug fixes

• Fix errors being thrown when detached: true or cleanup: false is used (#360) 211febe

https://github.com/sindresorhus/execa/compare/v2.0.3...v2.0.4

Bug fixes

• Add missing TypeScript definition for all (#345)

Documentation

• Add tip on how to execute the current package's binary (#339, #340)

Bug fixes

• Fix memory leak (#321, #330)
• Fix result.all not being constant across calls (#327, #330)

Bug fixes

• Correctly set the engines.node field in package.json. Supported Node versions are either ^8.12.0 or >=9.7.0 (#319, #323)

Documentation

• Improve the execa.command() documentation (#317)

Thanks to @GMartigny, @BendingBender, @tomsotte, @ammarbinfaisal, @zokker13, @stroncium, @satyarohith, @bradfordlemley, @coreyfarrell, @brandon93s, @dtinth, @papb for the great features and bug fixes they've contributed!

Please check the Medium article about this release!

Breaking changes

• Drop support for Node.js 6 (dce22670, #221)
• Remove execa.shell() and execa.shellSync(). The shell option should be used instead. (#219)
• Remove execa.stdout() and execa.stderr(). childProcessResult.stdout and childProcessResult.stderr should be used instead (#234)
• Remove error.code (number or string) in favor of error.exitCode (number) and error.exitCodeName (string) (#187, #250)
• Rename stripeEof option to stripFinalNewline (f8397ba9, 4d0dc88a, #238)
• Rename cmd (in childProcessResult and error) to command (#194)
• Default preferLocal option to false. If you are executing locally installed binaries, you'll need to manually specify preferLocal: true (#314)
• Ensure windowsHide option is always true, so that no window pops up on Windows. (8c886452)
• error.signal is now undefined instead of null when no signal was used (#193)
• Set error.killed to false when child process timed out (#227)
• Make error.killed always boolean (not undefined) (#229, #248)
• Ensure errors always have the same shape. (#276, #277, #283)
• error.stdout and error.stderr are now an empty string (instead of null) when the command failed. (#246)

Features

• Add TypeScript definition (#188, f2cb86ff, 7702b8ef, 4692dcd4, #251)
• Add execa.command() and execa.commandSync(). Those are the same as execa() except both file and arguments are specified in a single string. For example, execa('echo', ['unicorns']) is the same as execa.command('echo unicorns') (#182, #261, #262, #278, #279, #282)
• Retrieve interleaved stdout and stderr with childProcess.all and childProcessResult.all (#171, #264)
• Add execa.node() which (like child_process.fork()) allows you to execute a Node.js script as a child process (#200, #297, #299, #302, #303, #305, #306).
• If childProcess.kill() does not terminate a child process after 5 seconds, force it by sending SIGKILL. This can be configured using the forceKillAfterTimeout option. (#208, #272, #273, #280, #284, #285)
• Add childProcess.cancel() and error.isCanceled (#189, f24e7c72, #226, #309)
• error.stdout, error.stderr and error.all now contain the data that was sent before the child process exit. (#271)
• Improve error.message on child process failure (#180, #223, #230, #245, #269)
• Add .finally() to the child process promise (#174, 65139849)
• Increase maxBuffer option default value from 10 MB to 100 MB (#286)

Bug fixes

• Fix timeout option not working as expected (#199)
• Fix error.timedOut not working with execa.sync() (#249)
• Fix maxBuffer errors not using the same shape as the other errors (#266)
• Fix extendEnd option not working with shell option (#184)
• Fix stripFinalNewline option not applied on error properties (#240)
• Fix /q parameter not added when using cmd instead of cmd.exe (#203)
• Fix uncaught exception when using input option with a non-executable file (#212, #258)
• Fix errors on child processes waiting for stdout/stderr to complete (#270)
• Fix validating that the stdio option cannot be used together with stdin: 0 (#301).

Documentation

• Improve documentation (#158, #235, #237, #239, #241, #256)

Design

• Add a logo (#201)

Tests

• Fix various tests (f185a0e8, #185, #215, #216, #224, #218, #225, #231, #233, #247, #300)

Maintainers

• Add @ehmicky as an additional maintainer.

This is an alpha release for the upcoming 2.0.0.

Thanks to @GMartigny, @BendingBender, @tomsotte, @ammarbinfaisal, @zokker13, @stroncium, @satyarohith, @bradfordlemley, @coreyfarrell, @brandon93s, @dtinth, @papb for the great features and bug fixes they contributed!

Breaking changes

• Drop support for Node.js 6 (dce22670, #221)
• Remove execa.shell() and execa.shellSync(). The shell option should be used instead. (#219)
• Remove execa.stdout() and execa.stderr(). childProcessResult.stdout and childProcessResult.stderr should be used instead (#234)
• Remove error.code (number or string) in favor of error.exitCode (number) and error.exitCodeName (string) (#187, #250)
• Rename stripeEof option to stripFinalNewline (f8397ba9, 4d0dc88a, #238)
• Rename cmd (in childProcessResult and error) to command (#194)
• Default windowsHide option to true. This ensures no window pops up on Windows. (8c886452)
• error.signal is now undefined instead of null when no signal was used (#193)
• Set error.killed to false when child process timed out (#227)
• Make error.killed and error.isCanceled always boolean (not undefined) (#229, #248)
• Ensure errors always have the same shape. (#276, #277, #283)
• error.stdout and error.stderr are now an empty string (instead of null) when the command failed. (#246)

Features

• Add TypeScript definition (#188, f2cb86ff, 7702b8ef, 4692dcd4, #251)
• Add execa.command() and execa.commandSync(). Those are the same as execa() except both file and arguments are specified in a single string. For example, execa('echo', ['unicorns']) is the same as execa.command('echo unicorns') (#182, #261, #262, #278, #279, #282)
• Retrieve interleaved stdout and stderr with childProcess.all and childProcessResult.all (#171, #264)
• If childProcess.kill() does not terminate a child process after 5 seconds, force it by sending SIGKILL. This can be configured using the forceKillAftrerTimeout option. (#208, #272, #273, #280, #284, #285)
• Add childProcess.cancel() and error.isCanceled (#189, f24e7c72, #226)
• error.stdout, error.stderr and error.all now contain the data that was sent before the child process exit. (#271)
• Improve error.message on child process failure (#180, #223, #230, #245, #269)
• Add .finally() to the child process promise (#174, 65139849)
• Increase maxBuffer option default value from 10 MB to 100 MB (#286)

Bug fixes

• Fix timeout option not working as expected (#199)
• Fix error.timedOut not working with execa.sync() (#249)
• Fix maxBuffer errors not using the same shape as the other errors (#266)
• Fix extendEnd option not working with shell option (#184)
• Fix stripFinalNewline option not applied on error properties (#240)
• Fix /q parameter not added when using cmd instead of cmd.exe (#203)
• Fix uncaught exception when using input option with a non-executable file (#212, #258)
• Fix errors on child processes waiting for stdout/stderr to complete (#270)

Documentation

• Improve documentation (#158, #235, #237, #239, #241, #256)

Design

• Add a logo (#201)

Tests

• Fix various tests (f185a0e8, #185, #215, #216, #224, #218, #225, #231, #233, #247)

Maintainers

• Add @ehmicky as an additional maintainer.

This marks execa as stable. No actual changes since 0.11.0.