1 | # exec-sh
|
2 |
|
3 | [![NPM](https://nodei.co/npm/exec-sh.png)](https://nodei.co/npm/exec-sh/)
|
4 |
|
5 | [![NPM Downloads](https://img.shields.io/npm/dm/exec-sh.svg)](https://www.npmjs.com/package/exec-sh)
|
6 | [![Build Status](https://travis-ci.org/tsertkov/exec-sh.svg?branch=master)](https://travis-ci.org/tsertkov/exec-sh)
|
7 | [![Coverage Status](https://img.shields.io/coveralls/tsertkov/exec-sh.svg)](https://coveralls.io/r/tsertkov/exec-sh?branch=master)
|
8 | [![David Status](https://david-dm.org/tsertkov/exec-sh.png)](https://david-dm.org/tsertkov/exec-sh)
|
9 |
|
10 | > Execute shell command forwarding all stdio streams.
|
11 |
|
12 | ## Features
|
13 |
|
14 | exec-sh is a wrapper for [`child_process.spawn`](http://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) with some improvements:
|
15 |
|
16 | - Cross platform command execution:
|
17 | - Windows: `cmd /C COMMAND`
|
18 | - others: `sh -c COMMAND`
|
19 | - Fowrards all stdio streams to current terminal (by default):
|
20 | - `execSh("bash")`
|
21 | - `execsh("echo -n Say: && read i && echo Said:$i")`
|
22 | - stdout and stderr are passed to callback when available
|
23 | - `execSh("pwd", console.log)`
|
24 |
|
25 | ## Showcase
|
26 | ```javascript
|
27 | // JavaScript
|
28 |
|
29 | execSh("echo hello exec-sh && bash", { cwd: "/home" }, function(err){
|
30 | if (err) {
|
31 | console.log("Exit code: ", err.code);
|
32 | }
|
33 | });
|
34 | ```
|
35 |
|
36 | ```sh
|
37 | # Terminal output: interactive bash session
|
38 |
|
39 | hello exec-sh
|
40 | bash-3.2$ pwd
|
41 | /home
|
42 | bash-3.2$ exit 99
|
43 | exit
|
44 | Exit code: 99
|
45 | ```
|
46 |
|
47 | ## Usage
|
48 |
|
49 | ```javascript
|
50 | const execSh = require("../");
|
51 |
|
52 | // run interactive bash shell
|
53 | execSh("echo lorem && bash", { cwd: "/home" }, (err) => {
|
54 | if (err) {
|
55 | console.log("Exit code: ", err.code);
|
56 | return;
|
57 | }
|
58 |
|
59 | // collect streams output
|
60 | const child = execSh(["bash -c id", "echo lorem >&2"], true,
|
61 | (err, stdout, stderr) => {
|
62 | console.log("error: ", err);
|
63 | console.log("stdout: ", stdout);
|
64 | console.log("stderr: ", stderr);
|
65 | });
|
66 | });
|
67 | ```
|
68 |
|
69 | ## Promise Interface
|
70 |
|
71 | ```javascript
|
72 | const execShPromise = require("exec-sh").promise;
|
73 |
|
74 | // run interactive bash shell
|
75 | const run = async () => {
|
76 | let out;
|
77 |
|
78 | try {
|
79 | out = await execShPromise('pwd', true);
|
80 | } catch (e) {
|
81 | console.log('Error: ', e);
|
82 | console.log('Stderr: ', e.stderr);
|
83 | console.log('Stdout: ', e.stdout);
|
84 |
|
85 | return e;
|
86 | }
|
87 |
|
88 | console.log('out: ', out.stdout, out.stderr);
|
89 | }
|
90 |
|
91 | run();
|
92 | ```
|
93 |
|
94 | ## Public API
|
95 |
|
96 | ### `execSh(command, [options], [callback])`
|
97 |
|
98 | Execute shell command forwarding all stdio.
|
99 |
|
100 | **Parameters:**
|
101 |
|
102 | - `command {String|Array}` - The command to run, or array of commands
|
103 | - `[options] {Object|TRUE}` - Options object passed directly to [`child_process.spawn`](http://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options), when `TRUE` then `{ stdio: null }` used
|
104 | - `[callback] {Function}` - `callback(err, stdout, stderr)`
|
105 | - `err {Error|NULL}` - Error object. Has `code` property containing last command exit code when available
|
106 | - `stdout {String|NULL}` - aggregated stdout or `NULL` if not available
|
107 | - `stderr {String|NULL}` - aggregated stderr or `NULL` if not available
|
108 |
|
109 | **Return Values:**
|
110 |
|
111 | Returns [ChildProcess](http://nodejs.org/api/child_process.html#child_process_class_childprocess) object.
|
112 |
|
113 | ## Private API
|
114 | Complete API Documentation including private and public methods is generated from source code by JSDoc tool and is [available here](https://s3.eu-central-1.amazonaws.com/tsertkov-artifacts/exec-sh/master/jsdoc/index.html).
|
115 |
|
116 | ## Code Coverage
|
117 | Code coverage report for all files is [available here](https://s3.eu-central-1.amazonaws.com/tsertkov-artifacts/exec-sh/master/coverage/lcov-report/index.html).
|
118 |
|
119 | ## Scripts
|
120 |
|
121 | - `npm test` - run tests
|
122 | - `npm run jsdoc` - build jsdoc
|
123 | - `npm run dev` - run tests continuously
|
124 |
|
125 | ## License
|
126 |
|
127 | The MIT License (MIT)
|