# exec-sh

> Execute shell command forwarding all stdio.

Latest version **0.4.0** (published 2021-03-26) · MIT license · 0 weekly downloads

## Install

```sh
npm install exec-sh
pnpm add exec-sh
yarn add exec-sh
bun add exec-sh
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.0 |
| Published | 2021-03-26 |
| First published | 2014-06-14 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 23.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 64 |
| Author | Aleksandr Tsertkov |
| Maintainers | tsertkov |
| Keywords | exec, spawn, terminal, console, shell, command, child_process |

## Links

- npm: https://www.npmjs.com/package/exec-sh
- Repository: https://github.com/tsertkov/exec-sh
- Homepage: https://github.com/tsertkov/exec-sh#readme
- Issues: https://github.com/tsertkov/exec-sh/issues
- npm.io page: https://npm.io/package/exec-sh

## Alternatives

- [@salesforce/cli](https://npm.io/package/@salesforce/cli.md) — 389.7K weekly downloads
- [@mintlify/cli](https://npm.io/package/@mintlify/cli.md) — 208.9K weekly downloads
- [@grafana/e2e-selectors](https://npm.io/package/@grafana/e2e-selectors.md) — 128.7K weekly downloads
- [mintlify](https://npm.io/package/mintlify.md) — 112.0K weekly downloads
- [@intlayer/cli](https://npm.io/package/@intlayer/cli.md) — 22.8K weekly downloads

## Recent versions

- 0.4.0 (latest) — 2021-03-26
- 0.1.2 (0.1.2) — 2014-06-14
- 0.3.6 — 2021-03-24
- 0.3.5 — 2021-03-22
- 0.3.4 — 2019-11-07
- 0.3.3 — 2019-11-07
- 0.3.2 — 2018-10-17
- 0.3.1 — 2018-09-15
- 0.3.0 — 2018-09-13
- 0.2.2 — 2018-06-26
- 0.2.1 — 2017-09-07
- 0.2.0 — 2014-11-26
- 0.1.4 — 2014-11-26
- 0.1.3 — 2014-06-14
- 0.1.0 — 2014-06-14

## README

# exec-sh

[![NPM](https://nodei.co/npm/exec-sh.png)](https://nodei.co/npm/exec-sh/)

[![NPM Downloads](https://img.shields.io/npm/dm/exec-sh.svg)](https://www.npmjs.com/package/exec-sh)
[![Build Status](https://travis-ci.org/tsertkov/exec-sh.svg?branch=master)](https://travis-ci.org/tsertkov/exec-sh)
[![Coverage Status](https://img.shields.io/coveralls/tsertkov/exec-sh.svg)](https://coveralls.io/r/tsertkov/exec-sh?branch=master)
[![David Status](https://david-dm.org/tsertkov/exec-sh.png)](https://david-dm.org/tsertkov/exec-sh)

> Execute shell command forwarding all stdio streams.

## Features

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:

- Cross platform command execution:
  - Windows: `cmd /C COMMAND`
  - others: `sh -c COMMAND`
- Fowrards all stdio streams to current terminal (by default):
  - `execSh("bash")`
  - `execsh("echo -n Say: && read i && echo Said:$i")`
- stdout and stderr are passed to callback when available
  - `execSh("pwd", console.log)`

## Showcase
```javascript
// JavaScript

execSh("echo hello exec-sh && bash", { cwd: "/home" }, function(err){
  if (err) {
    console.log("Exit code: ", err.code);
  }
});
```

```sh
# Terminal output: interactive bash session

hello exec-sh
bash-3.2$ pwd
/home
bash-3.2$ exit 99
exit
Exit code:  99
```

## Usage

```javascript
const execSh = require("../");

// run interactive bash shell
execSh("echo lorem && bash", { cwd: "/home" }, (err) => {
  if (err) {
    console.log("Exit code: ", err.code);
    return;
  }

  // collect streams output
  const child = execSh(["bash -c id", "echo lorem >&2"], true,
    (err, stdout, stderr) => {
      console.log("error: ", err);
      console.log("stdout: ", stdout);
      console.log("stderr: ", stderr);
    });
});
```

## Promise Interface

```javascript
const execShPromise = require("exec-sh").promise;

// run interactive bash shell
const run = async () => {
  let out;

  try {
    out = await execShPromise('pwd', true);
  } catch (e) {
    console.log('Error: ', e);
    console.log('Stderr: ', e.stderr);
    console.log('Stdout: ', e.stdout);

    return e;
  }

  console.log('out: ', out.stdout, out.stderr);
}

run();
```

## Public API

### `execSh(command, [options], [callback])`

Execute shell command forwarding all stdio.

**Parameters:**

- `command {String|Array}` - The command to run, or array of commands
- `[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
- `[callback] {Function}` - `callback(err, stdout, stderr)`
 - `err {Error|NULL}` - Error object. Has `code` property containing last command exit code when available
 - `stdout {String|NULL}` - aggregated stdout or `NULL` if not available
 - `stderr {String|NULL}` - aggregated stderr or `NULL` if not available

**Return Values:**

Returns [ChildProcess](http://nodejs.org/api/child_process.html#child_process_class_childprocess) object.

## Private API
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).

## Code Coverage
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).

## Scripts

- `npm test` - run tests
- `npm run jsdoc` - build jsdoc
- `npm run dev` - run tests continuously

## License

The MIT License (MIT)

---
_Source: https://npm.io/package/exec-sh · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._