# shellton

> execute external processed with a simple API

Latest version **5.1.0** (published 2023-02-20) · ISC license · 0 weekly downloads

## Install

```sh
npm install shellton
pnpm add shellton
yarn add shellton
bun add shellton
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.1.0 |
| Published | 2023-02-20 |
| First published | 2016-01-12 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 16.9 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Kiril Vatev |
| Maintainers | kirilv |
| Keywords | unix, shell, exec, spawn, command |

## Links

- npm: https://www.npmjs.com/package/shellton
- Repository: https://github.com/catdad/shellton
- Homepage: https://github.com/catdad/shellton#readme
- Issues: https://github.com/catdad/shellton/issues
- npm.io page: https://npm.io/package/shellton

## Dependencies (2)

- [async](https://npm.io/package/async.md) ^2.0.1
- [lodash](https://npm.io/package/lodash.md) ^4.17.10

## 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

- 5.1.0 (latest) — 2023-02-20
- 5.0.0 — 2018-12-13
- 4.1.0 — 2018-07-04
- 4.0.0 — 2018-03-11
- 3.1.0 — 2017-02-27
- 3.0.2 — 2017-01-05
- 3.0.1 — 2016-12-22
- 3.0.0 — 2016-11-13
- 2.1.1 — 2016-10-01
- 2.1.0 — 2016-09-10
- 2.0.0 — 2016-06-26
- 1.3.2 — 2016-03-12
- 1.3.1 — 2016-02-06
- 1.3.0 — 2016-02-06
- 1.2.1 — 2016-01-23
- … 4 more at https://npm.io/package/shellton/versions

## README

# shellton

[![Build][1]][2]
[![Test Coverage][3]][4]
[![Code Climate][5]][6]
[![Downloads][7]][8]
[![Version][9]][8]

[1]: https://img.shields.io/github/actions/workflow/status/catdad/shellton/ci.yml?branch=master&logo=github
[2]: https://github.com/catdad/shellton/actions/workflows/ci.yml?query=branch%3Amaster

[3]: https://codeclimate.com/github/catdad/shellton/badges/coverage.svg
[4]: https://codeclimate.com/github/catdad/shellton/coverage

[5]: https://codeclimate.com/github/catdad/shellton/badges/gpa.svg
[6]: https://codeclimate.com/github/catdad/shellton

[7]: https://img.shields.io/npm/dm/shellton.svg
[8]: https://www.npmjs.com/package/shellton
[9]: https://img.shields.io/npm/v/shellton.svg

## Install

    npm install --save shellton
    
## Use

### Basic example

```javascript
var shellton = require('shellton');

shellton('echo all the things', function(err, stdout, stderr) {
    console.log(stdout); // all the things
});
```

### Using IO streams

You can pipe the standard output streams from the child process, as such:

```javascript
var output = fs.createWriteStream('script-output.txt');

shellton({
    task: 'node script.js',
    stdout: output
    // you can also do stderr here, if you need
    // or just pipe it to the parent process io stream
    stderr: process.stderr
}, function(err, stdout, stderr) {
    console.log('script.js has exited');
});
```

You can also provide input to the external process, as such:

```javascript
var input = fs.createReadStream('my-script.js');

shellton({
    task: 'node',
    stdin: input
}, function(err, stdout, stderr) {
    console.log('my-script.js has exited');
});
```

Use your imagination here, and you can come up with some much more useful cases.

```javascript
var shellton = require('shellton');
var through = require('through2');
var chalk = require('chalk');

function colorStream(name, writeStream) {
    writeStream = writeStream || process.stdout;
    
    var colorFunc = (chalk[name] || chalk.white).bind(chalk);
    
    var stream = through();
    stream.on('data', function(chunk) {
        writeStream.write(colorFunc(chunk));
    });
    
    return stream;
}

var input = through();
// write to the parent's output stream in green
var output = colorStream('green', process.stdout);
// write to the parent's error stream in red
var error = colorStream('red', process.stderr);

shellton({
    task: 'node',
    stdin: input,
    stdout: output,
    stderr: error
});

// use any dynamically generated javascript
input.write('console.log("output is green");');
input.write('console.error("errors are red");');
input.end();
```

## API

### `shellton(options, callback)`

`options` {string | Object} : The options defining the external task to execute. This parameter is required.
- When given a string, this is the command line command being executed. You can supply a full command, as you would normally type into bash or the Windows command prompt.
- When given an object, the following properties are available:
  - `task` {string} : the command to executed.
  - `stdin` {Stream} : a stream to pipe into the command.
  - `stdout` {Stream} : a stream to where the standard output of the command will be piped.
  - `stderr` {Stream} : a stream to where the standard error of the command will be piped.
  - `cwd` {string} : the directory from where the command will be executed. The default is the current directory of the parent process.
  - `env` {Object} : the environment variables for the child process. Values here will be merged with an overwrite values in the current `process.env`.
  - `encoding` {string} : the encoding to use to the data provided to the callback. The options are `utf8` and `buffer`, with `utf8` being the default.
  
`callback` {function} : The callback to call when the child process exists. This parameter is optional. It receives the following parameters, in order:
- `error` {Error} : An error that occurred when executing the command. This generally means the command exited with a code other than 0. `error.code` specifies the exit code of the command.
- `stdout` {string|Buffer} : A string representation of the standard output of the command. If the command outputs binary, you will likely want to read directly from `stdout` in the `options` object.
- `stderr` {string|Buffer} : A string representation of the standard error of the command. If the command outputs binary, you will likely want to read directly from `stderr` in the `options` object.

[![Analytics](https://ga-beacon.appspot.com/UA-17159207-7/shellton/readme?flat)](https://github.com/igrigorik/ga-beacon)

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