1 | # execa [![Build Status: Linux](https://travis-ci.org/sindresorhus/execa.svg?branch=master)](https://travis-ci.org/sindresorhus/execa) [![Build status: Windows](https://ci.appveyor.com/api/projects/status/x5ajamxtjtt93cqv/branch/master?svg=true)](https://ci.appveyor.com/project/sindresorhus/execa/branch/master) [![Coverage Status](https://coveralls.io/repos/github/sindresorhus/execa/badge.svg?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
|
27 | const execa = require('execa');
|
28 |
|
29 | execa('echo', ['unicorns']).then(result => {
|
30 | console.log(result.stdout);
|
31 | //=> 'unicorns'
|
32 | });
|
33 |
|
34 | // pipe the child process stdout to the current stdout
|
35 | execa('echo', ['unicorns']).stdout.pipe(process.stdout);
|
36 |
|
37 | execa.shell('echo unicorns').then(result => {
|
38 | console.log(result.stdout);
|
39 | //=> 'unicorns'
|
40 | });
|
41 |
|
42 | // example of catching an error
|
43 | execa.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 | // example of catching an error with a sync method
|
60 | try {
|
61 | execa.shellSync('exit 3');
|
62 | } catch (err) {
|
63 | console.log(err);
|
64 | /*
|
65 | {
|
66 | message: 'Command failed: /bin/sh -c exit 3'
|
67 | code: 3,
|
68 | signal: null,
|
69 | cmd: '/bin/sh -c exit 3',
|
70 | stdout: '',
|
71 | stderr: '',
|
72 | timedOut: false
|
73 | }
|
74 | */
|
75 | }
|
76 | ```
|
77 |
|
78 |
|
79 | ## API
|
80 |
|
81 | ### execa(file, [arguments], [options])
|
82 |
|
83 | Execute a file.
|
84 |
|
85 | Think of this as a mix of `child_process.execFile` and `child_process.spawn`.
|
86 |
|
87 | Returns 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.
|
88 |
|
89 | ### execa.stdout(file, [arguments], [options])
|
90 |
|
91 | Same as `execa()`, but returns only `stdout`.
|
92 |
|
93 | ### execa.stderr(file, [arguments], [options])
|
94 |
|
95 | Same as `execa()`, but returns only `stderr`.
|
96 |
|
97 | ### execa.shell(command, [options])
|
98 |
|
99 | Execute a command through the system shell. Prefer `execa()` whenever possible, as it's both faster and safer.
|
100 |
|
101 | Returns a [`child_process` instance](https://nodejs.org/api/child_process.html#child_process_class_childprocess).
|
102 |
|
103 | The `child_process` instance is enhanced to also be promise for a result object with `stdout` and `stderr` properties.
|
104 |
|
105 | ### execa.sync(file, [arguments], [options])
|
106 |
|
107 | Execute a file synchronously.
|
108 |
|
109 | Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
|
110 |
|
111 | This method throws an `Error` if the command fails.
|
112 |
|
113 | ### execa.shellSync(file, [options])
|
114 |
|
115 | Execute a command synchronously through the system shell.
|
116 |
|
117 | Returns the same result object as [`child_process.spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options).
|
118 |
|
119 | ### options
|
120 |
|
121 | Type: `Object`
|
122 |
|
123 | #### cwd
|
124 |
|
125 | Type: `string`<br>
|
126 | Default: `process.cwd()`
|
127 |
|
128 | Current working directory of the child process.
|
129 |
|
130 | #### env
|
131 |
|
132 | Type: `Object`<br>
|
133 | Default: `process.env`
|
134 |
|
135 | Environment key-value pairs. Extends automatically from `process.env`. Set `extendEnv` to `false` if you don't want this.
|
136 |
|
137 | #### extendEnv
|
138 |
|
139 | Type: `boolean`<br>
|
140 | Default: `true`
|
141 |
|
142 | Set to `false` if you don't want to extend the environment variables when providing the `env` property.
|
143 |
|
144 | #### argv0
|
145 |
|
146 | Type: `string`
|
147 |
|
148 | Explicitly set the value of `argv[0]` sent to the child process. This will be set to `command` or `file` if not specified.
|
149 |
|
150 | #### stdio
|
151 |
|
152 | Type: `Array` `string`<br>
|
153 | Default: `pipe`
|
154 |
|
155 | Child's [stdio](https://nodejs.org/api/child_process.html#child_process_options_stdio) configuration.
|
156 |
|
157 | #### detached
|
158 |
|
159 | Type: `boolean`
|
160 |
|
161 | Prepare 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).
|
162 |
|
163 | #### uid
|
164 |
|
165 | Type: `number`
|
166 |
|
167 | Sets the user identity of the process.
|
168 |
|
169 | #### gid
|
170 |
|
171 | Type: `number`
|
172 |
|
173 | Sets the group identity of the process.
|
174 |
|
175 | #### shell
|
176 |
|
177 | Type: `boolean` `string`<br>
|
178 | Default: `false`
|
179 |
|
180 | If `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.
|
181 |
|
182 | #### stripEof
|
183 |
|
184 | Type: `boolean`<br>
|
185 | Default: `true`
|
186 |
|
187 | [Strip EOF](https://github.com/sindresorhus/strip-eof) (last newline) from the output.
|
188 |
|
189 | #### preferLocal
|
190 |
|
191 | Type: `boolean`<br>
|
192 | Default: `true`
|
193 |
|
194 | Prefer locally installed binaries when looking for a binary to execute.<br>
|
195 | If you `$ npm install foo`, you can then `execa('foo')`.
|
196 |
|
197 | #### localDir
|
198 |
|
199 | Type: `string`<br>
|
200 | Default: `process.cwd()`
|
201 |
|
202 | Preferred path to find locally installed binaries in (use with `preferLocal`).
|
203 |
|
204 | #### input
|
205 |
|
206 | Type: `string` `Buffer` `stream.Readable`
|
207 |
|
208 | Write some input to the `stdin` of your binary.<br>
|
209 | Streams are not allowed when using the synchronous methods.
|
210 |
|
211 | #### reject
|
212 |
|
213 | Type: `boolean`<br>
|
214 | Default: `true`
|
215 |
|
216 | Setting this to `false` resolves the promise with the error instead of rejecting it.
|
217 |
|
218 | #### cleanup
|
219 |
|
220 | Type: `boolean`<br>
|
221 | Default: `true`
|
222 |
|
223 | Keep track of the spawned process and `kill` it when the parent process exits.
|
224 |
|
225 | #### encoding
|
226 |
|
227 | Type: `string`<br>
|
228 | Default: `utf8`
|
229 |
|
230 | Specify the character encoding used to decode the `stdout` and `stderr` output.
|
231 |
|
232 | #### timeout
|
233 |
|
234 | Type: `number`<br>
|
235 | Default: `0`
|
236 |
|
237 | If 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.
|
238 |
|
239 | #### maxBuffer
|
240 |
|
241 | Type: `number`<br>
|
242 | Default: `10000000` (10MB)
|
243 |
|
244 | Largest amount of data in bytes allowed on `stdout` or `stderr`.
|
245 |
|
246 | #### killSignal
|
247 |
|
248 | Type: `string` `number`<br>
|
249 | Default: `SIGTERM`
|
250 |
|
251 | Signal value to be used when the spawned process will be killed.
|
252 |
|
253 | #### stdin
|
254 |
|
255 | Type: `string` `number` `Stream` `undefined` `null`<br>
|
256 | Default: `pipe`
|
257 |
|
258 | Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
|
259 |
|
260 | #### stdout
|
261 |
|
262 | Type: `string` `number` `Stream` `undefined` `null`<br>
|
263 | Default: `pipe`
|
264 |
|
265 | Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
|
266 |
|
267 | #### stderr
|
268 |
|
269 | Type: `string` `number` `Stream` `undefined` `null`<br>
|
270 | Default: `pipe`
|
271 |
|
272 | Same options as [`stdio`](https://nodejs.org/dist/latest-v6.x/docs/api/child_process.html#child_process_options_stdio).
|
273 |
|
274 | #### windowsVerbatimArguments
|
275 |
|
276 | Type: `boolean`<br>
|
277 | Default: `false`
|
278 |
|
279 | If `true`, no quoting or escaping of arguments is done on Windows. Ignored on other platforms. This is set to `true` automatically when the `shell` option is `true`.
|
280 |
|
281 |
|
282 | ## Tips
|
283 |
|
284 | ### Save and pipe output from a child process
|
285 |
|
286 | Let's say you want to show the output of a child process in real-time while also saving it to a variable.
|
287 |
|
288 | ```js
|
289 | const execa = require('execa');
|
290 | const getStream = require('get-stream');
|
291 |
|
292 | const stream = execa('echo', ['foo']).stdout;
|
293 |
|
294 | stream.pipe(process.stdout);
|
295 |
|
296 | getStream(stream).then(value => {
|
297 | console.log('child output:', value);
|
298 | });
|
299 | ```
|
300 |
|
301 |
|
302 | ## License
|
303 |
|
304 | MIT © [Sindre Sorhus](https://sindresorhus.com)
|