# gulp-run-command

> A simple way to run command-line programs from gulp in a cross-platform way.

Latest version **0.0.10** (published 2019-11-13) · MIT license · 0 weekly downloads

## Install

```sh
npm install gulp-run-command
pnpm add gulp-run-command
yarn add gulp-run-command
bun add gulp-run-command
```

## Health

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

Positive: has types; no vulnerabilities.

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

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.10 |
| Published | 2019-11-13 |
| First published | 2016-09-19 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 132.7 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 23 |
| Author | Gregory Benner |
| Maintainers | klathmon |

## Links

- npm: https://www.npmjs.com/package/gulp-run-command
- Repository: https://github.com/Klathmon/gulp-run-command
- Homepage: https://github.com/Klathmon/gulp-run-command#readme
- Issues: https://github.com/Klathmon/gulp-run-command/issues
- npm.io page: https://npm.io/package/gulp-run-command

## Dependencies (4)

- [spawn-args](https://npm.io/package/spawn-args.md) 0.2.0
- [cross-spawn](https://npm.io/package/cross-spawn.md) 4.0.0
- [timeout-as-promise](https://npm.io/package/timeout-as-promise.md) ^1.0.0
- [babel-plugin-transform-runtime](https://npm.io/package/babel-plugin-transform-runtime.md) 6.15.0

## Recent versions

- 0.0.10 (latest) — 2019-11-13
- 0.0.8-beta.4 (beta) — 2017-05-24
- 0.0.9 — 2017-07-19
- 0.0.8-beta.3 — 2017-05-24
- 0.0.8-beta.2 — 2017-05-24
- 0.0.7 — 2016-10-07
- 0.0.6 — 2016-09-22
- 0.0.5 — 2016-09-21
- 0.0.2 — 2016-09-19

## README

# gulp-run-command

[![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg)](http://standardjs.com/)

A simple way to run command-line programs from gulp in a cross-platform way.

## Installation

`npm install gulp-run-command`

## Usage
```js
import gulp from 'gulp'
import run from 'gulp-run-command' // or `var run = require('gulp-run-command').default` for ES5

gulp.task('clean', run('rm -rf build'))
gulp.task('build', ['clean'], run('babel index.js --out-file index.es5.js', {
  env: { NODE_ENV: 'production' }
}))

```

## API

### run(command, options)

#### commands

type: `Array` or `String`

A command will be run "as if you typed it in the console". An array of commands will be run sequentially (waiting for each to finish before the next begins), stdin will be blank for all commands. Commands will be run like they are from `npm scripts`, locally installed modules can be run without having to prefix `node_modules/.bin`.

#### options.quiet

type: `Boolean`  
default: `false`

Setting to `true` will ignore all output from the command (both stdout and stderr)

#### options.ignoreErrors

type: `Boolean`  
default: `false`

Setting to `true` will ignore any errors that the command throws. It will also ignore return values.

#### options.cwd

type: `String`  
default: [`process.cwd()`](http://nodejs.org/api/process.html#process_process_cwd)

Sets the current working directory for the command. This is where the `node_modules/.bin` is searched for as well to be added to the path.

#### options.timeout

type: `Number`  
default: `undefined` (no timeout)

The max time (in milliseconds) that the command is allowed to run

#### options.env

type: `Object`  
default: `{}`

This object will be **added to** the normal environment, overwriting defaults with what you pass in. So if your "main" environment includes `NODE_ENV="development"` and you pass in `{ NODE_ENV: 'production'}` the command will be run with `NODE_ENV="production"`.


## FAQ

**Why?**  
I loved Gulp's dependency management and plugin ecosystem, but I hated having to use file streams or plugins which wrap my tools which are often out of date, buggy, or missing functionality. This plugin lets you define gulp tasks as command line commands which will be run. Most tools have a command line interface, so you are cutting out several unnecessary layers and giving yourself more flexibility.

**What not just use [`gulp-shell`](https://github.com/sun-zheng-an/gulp-shell)?**  
`gulp-shell` is great, but sadly it uses [`child_process.exec`](https://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback). That means that output from the plugin is buffered and only output in chunks. This causes issues with command line applications that are expecting direct access to the console. (it also has a tendency to strip colors from the output). This uses [`child_process.spawn`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) which is more difficult to use, but works much better.

**Can you add this new feature?**  
Maybe... I'm trying to keep this a small single-purpose plugin, but if you want a feature feel free to open an issue and I'll take a look.

**Gulp@4 support**  
In order to use `gulp-run-command` with Gulp@4, you need to call the return function after passing the command and options (formally known as currying). For example:
```javascript
gulp.task('clean', async () => run('echo "Hello World!"')());
```

## Inspiration

* [`gulp-shell`](https://github.com/sun-zheng-an/gulp-shell) came up with the idea, I just changed it's underlying implementation.

## Contributing

The code is written in ES6 using [Javascript Standard Style](https://github.com/feross/standard). Feel free to make PRs adding features you want, but please try to follow Standard. Also, codumentation/readme PRs are more then welcome!

## License

[MIT](LICENSE.md) Copyright (c) [Gregory Benner](https://github.com/Klathmon)

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