# gulp-shell
[](https://npmjs.org/package/gulp-shell)
[](https://travis-ci.org/sun-zheng-an/gulp-shell)
[](https://coveralls.io/r/sun-zheng-an/gulp-shell)
[](https://david-dm.org/sun-zheng-an/gulp-shell)
[](https://npmjs.org/package/gulp-shell)
> A handy command line interface for gulp
## Installation
```shell
npm install --save-dev gulp-shell
```
## Usage
```js
const gulp = require('gulp')
const shell = require('gulp-shell')
gulp.task('example', () => {
return gulp
.src('*.js', { read: false })
.pipe(shell(['echo <%= file.path %>']))
})
```
Or you can use this shorthand:
```js
gulp.task('greet', shell.task('echo Hello, World!'))
```
You can find more examples in the [gulpfile](https://github.com/sun-zheng-an/gulp-shell/blob/master/gulpfile.ts) of this project.
**WARNING**: Running commands like ~~`gulp.src('').pipe(shell('whatever'))`~~ is [considered as an anti-pattern](https://github.com/sun-zheng-an/gulp-shell/issues/55). **PLEASE DON'T DO THAT ANYMORE**.
## API
### shell(commands, options) or shell.task(commands, options)
#### commands
type: `string` or `Array<string>`
A command can be a [template][] which can be interpolated by some [file][] info (e.g. `file.path`).
**WARNING**: [Using command templates can be extremely dangerous](https://github.com/sun-zheng-an/gulp-shell/issues/83). Don't shoot yourself in the foot by ~~passing arguments like `$(rm -rf $HOME)`~~.
#### 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 can be a [template][] which can be interpolated by some [file][] info (e.g. `file.path`).
#### options.env
type: `object`
By default, all the commands will be executed in an environment with all the variables in [`process.env`](http://nodejs.org/api/process.html#process_process_env) and `PATH` prepended by `./node_modules/.bin` (allowing you to run executables in your Node's dependencies).
You can override any environment variables with this option.
For example, setting it to `{ PATH: process.env.PATH }` will reset the `PATH` if the default one brings your some troubles.
#### options.shell
type: `string`
default: `/bin/sh` on UNIX, and `cmd.exe` on Windows
Change it to `bash` if you like.
#### options.quiet
type: `boolean`
default: `false`
By default, it will print the command output.
#### options.verbose
type: `boolean`
default: `false`
Set to `true` to print the command(s) to stdout as they are executed
#### options.ignoreErrors
type: `boolean`
default: `false`
By default, it will emit an `error` event when the command finishes unsuccessfully.
#### options.errorMessage
type: `string`
default: `` Command `<%= command %>` failed with exit code <%= error.code %> ``
You can add a custom error message for when the command fails.
This can be a [template][] which can be interpolated with the current `command`, some [file][] info (e.g. `file.path`) and some error info (e.g. `error.code`).
#### options.templateData
type: `object`
The data that can be accessed in [template][].
[template]: http://lodash.com/docs#template
[file]: https://github.com/wearefractal/vinyl
## Changelog
Details changes for each release are documented in the [release notes](https://github.com/sun-zheng-an/gulp-shell/releases).