1# execa [](https://travis-ci.org/sindresorhus/execa) [](https://ci.appveyor.com/project/sindresorhus/execa/branch/master) [](https://coveralls.io/github/sindresorhus/execa?branch=master) 2 3> A better [`child_process`](https://nodejs.org/api/child_process.html) 4 5 6## Why 7 8- Promise interface. 9- [Strips EOF](https://github.com/sindresorhus/strip-eof) from the output so you don't have to `stdout.trim()`. 10- Supports [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) binaries cross-platform. 11- [Improved Windows support.](https://github.com/IndigoUnited/node-cross-spawn#why) 12- Higher max buffer. 10 MB instead of 200 KB. 13- [Executes locally installed binaries by name.](#preferlocal) 14- [Cleans up spawned processes when the parent process dies.](#cleanup) 15 16 17## Install 18 19``` 20$ npm install --save execa 21``` 22 23 24## Usage 25 26```js 27const execa = require('execa'); 28 29execa('echo', ['unicorns']).then(result => { 30 console.log(result.stdout); 31 //=> 'unicorns' 32}); 33 34// pipe the child process stdout to the current stdout 35execa('echo', ['unicorns']).stdout.pipe(process.stdout); 36 37execa.shell('echo unicorns').then(result => { 38 console.log(result.stdout); 39 //=> 'unicorns' 40}); 41 42// example of catching an error 43execa.shell('exit 3').catch(error => { 44 console.log(error); 45 /* 46 { 47 message: 'Command failed: /bin/sh -c exit 3' 48 killed: false, 49 code: 3, 50 signal: null, 51 cmd: '/bin/sh -c exit 3', 52 stdout: '', 53 stderr: '', 54 timedOut: false 55 } 56 */ 57}); 58``` 59 60 61## API 62 63### execa(file, [arguments], [options]) 64 65Execute a file. 66 67Think of this as a mix of `child_process.execFile` and `child_process.spawn`. 68 69Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess), which is enhanced to also be a `Promise` for a result `Object` with `stdout` and `stderr` properties. 70 71### execa.stdout(file, [arguments], [options]) 72 73Same as `execa()`, but returns only `stdout`. 74 75### execa.stderr(file, [arguments], [options]) 76 77Same as `execa()`, but returns only `stderr`. 78 79### execa.shell(command, [options]) 80 81Execute a command through the system shell. Prefer `execa()` whenever possible, as it's both faster and safer. 82 83Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess). 84 85The `child_process` instance is enhanced to also be promise for a result object with `stdout` and `stderr` properties. 86 87### execa.sync(file, [arguments], [options]) 88 89Execute a file synchronously. 90 91Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options). 92 93This method throws an `Error` if the command fails. 94 95### execa.shellSync(file, [options]) 96 97Execute a command synchronously through the system shell. 98 99Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options). 100 101### options 102 103Type: `Object` 104 105#### cwd 106 107Type: `string`<br> 108Default: `process.cwd()` 109 110Current working directory of the child process. 111 112#### env 113 114Type: `Object`<br> 115Default: `process.env` 116 117Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this. 118 119#### extendEnv 120 121Type: `boolean`<br> 122Default: `true` 123 124Set to `false` if you don't want to extend the environment variables when providing the `env` property. 125 126#### argv0 127 128Type: `string` 129 130Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified. 131 132#### stdio 133 134Type: `Array` `string`<br> 135Default: `pipe` 136 137Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration. 138 139#### detached 140 141Type: `boolean` 142 143Prepare child to run independently of its parent process. Specific behavior [depends on the platform](https://nodejs.org/api/child_process.html#child_process_options_detached). 144 145#### uid 146 147Type: `number` 148 149Sets the user identity of the process. 150 151#### gid 152 153Type: `number` 154 155Sets the group identity of the process. 156 157#### shell 158 159Type: `boolean` `string`<br> 160Default: `false` 161 162If `true`, runs `command` inside of a shell. Uses `/bin/sh` on UNIX and `cmd.exe` on Windows. A different shell can be specified as a string. The shell should understand the `-c` switch on UNIX or `/d /s /c` on Windows. 163 164#### stripEof 165 166Type: `boolean`<br> 167Default: `true` 168 169[Strip EOF](https://github.com/sindresorhus/strip-eof) (last newline) from the output. 170 171#### preferLocal 172 173Type: `boolean`<br> 174Default: `true` 175 176Prefer locally installed binaries when looking for a binary to execute.<br> 177If you `$ npm install foo`, you can then `execa('foo')`. 178 179#### localDir 180 181Type: `string`<br> 182Default: `process.cwd()` 183 184Preferred path to find locally installed binaries in (use with `preferLocal`). 185 186#### input 187 188Type: `string` `Buffer` `stream.Readable` 189 190Write some input to the `stdin` of your binary.<br> 191Streams are not allowed when using the synchronous methods. 192 193#### reject 194 195Type: `boolean`<br> 196Default: `true` 197 198Setting this to `false` resolves the promise with the error instead of rejecting it. 199 200#### cleanup 201 202Type: `boolean`<br> 203Default: `true` 204 205Keep track of the spawned process and `kill` it when the parent process exits. 206 207#### encoding 208 209Type: `string`<br> 210Default: `utf8` 211 212Specify the character encoding used to decode the `stdout` and `stderr` output. 213 214#### timeout 215 216Type: `number`<br> 217Default: `0` 218 219If timeout is greater than `0`, the parent will send the signal identified by the `killSignal` property (the default is `SIGTERM`) if the child runs longer than timeout milliseconds. 220 221#### maxBuffer 222 223Type: `number`<br> 224Default: `10000000` (10MB) 225 226Largest amount of data in bytes allowed on `stdout` or `stderr`. 227 228#### killSignal 229 230Type: `string` `number`<br> 231Default: `SIGTERM` 232 233Signal value to be used when the spawned process will be killed. 234 235#### stdin 236 237Type: `string` `number` `Stream` `undefined` `null`<br> 238Default: `pipe` 239 240Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). 241 242#### stdout 243 244Type: `string` `number` `Stream` `undefined` `null`<br> 245Default: `pipe` 246 247Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). 248 249#### stderr 250 251Type: `string` `number` `Stream` `undefined` `null`<br> 252Default: `pipe` 253 254Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio). 255 256 257## Tips 258 259### Save and pipe output from a child process 260 261Let's say you want to show the output of a child process in real-time while also saving it to a variable. 262 263```js 264const execa = require('execa'); 265const getStream = require('get-stream'); 266 267const stream = execa('echo', ['foo']).stdout; 268 269stream.pipe(process.stdout); 270 271getStream(stream).then(value => { 272 console.log('child output:', value); 273}); 274``` 275 276 277## License 278 279MIT © [Sindre Sorhus](https://sindresorhus.com) 280
){kind=link}
){kind=link}