🌜
🌞
grunt-shell

grunt-shell

v4.0.0

Run shell commands

npm install grunt-shell

README

grunt-shell

Run shell commands

A good way to interact with other CLI tools. For example, get the current Git branch with git branch.

Install

npm install --save-dev grunt-shell

Usage

require('load-grunt-tasks')(grunt);

grunt.initConfig({
    shell: {
        options: {
            stderr: false
        },
        target: {
            command: 'ls'
        },
        another: 'ls ./src' // Shorthand
    }
});

grunt.registerTask('default', ['shell']);

Examples

Run command

Create a folder named test.

grunt.initConfig({
    shell: {
        makeDir: {
            command: 'mkdir test'
        }
    }
});

The command property supports templates:

grunt.initConfig({
    testDir: 'test',
    shell: {
        makeDir: {
            command: 'mkdir <%= testDir %>'
        }
    }
});

You can also supply a function that returns the command:

grunt.initConfig({
    shell: {
        hello: {
            command: () => 'echo hello'
        }
    }
});

Which can also take arguments:

module.exports = grunt => {
    grunt.loadNpmTasks('grunt-shell');
    grunt.initConfig({
        shell: {
            greet: {
                command: greeting => `echo ${greeting}`
            }
        }
    });
    grunt.registerTask('default', ['shell:greet:hello']);
}

Run command and display the output

Output a directory listing in your Terminal.

grunt.initConfig({
    shell: {
        dirListing: {
            command: 'ls'
        }
    }
});

Custom callback

Do whatever you want with the output.

function log(error, stdout, stderr, callback) {
    if (error) {
        callback(error);
        return;
    }

    console.log(stdout);
    callback();
}

grunt.initConfig({
    shell: {
        dirListing: {
            command: 'ls',
            options: {
                callback: log
            }
        }
    }
});

Option passed to the .exec() method

Run a command in another directory. In this example, we run it in a subfolder using the cwd (current working directory) option.

grunt.initConfig({
    shell: {
        subfolderLs: {
            command: 'ls',
            options: {
                stderr: false,
                execOptions: {
                    cwd: 'tasks'
                }
            }
        }
    }
});

Multiple commands

Run multiple commands by placing them in an array which is joined using && or ;. && means run this only if the previous command succeeded. You can also use & to have the commands run concurrently (by executing all commands except the last one in a subshell).

grunt.initConfig({
    shell: {
        multiple: {
            command: [
                'mkdir test',
                'cd test',
                'ls'
            ].join('&&')
        }
    }
});

Config

command

Required
Type: string | Function

Command to run or a function which returns the command. Supports underscore templates.

Command can be omitted by directly setting the target with the command.

cwd

Type: string

Shortcut. Same as options.execOptions.cwd (see below).

Options

stdout

Type: boolean
Default: true

Show stdout in the terminal.

stderr

Type: boolean
Default: true

Show stderr in the terminal.

stdin

Type: boolean
Default: true

Forward the terminal's stdin to the command.

failOnError

Type: boolean
Default: true

Fail task if it encounters an error. Does not apply if you specify a callback.

stdinRawMode

Type: boolean
Default: false

Set stdin to act as a raw device.

callback(error, stdout, stderr, callback)

Type: Function

Lets you override the default callback with your own.

Make sure to call the callback method when you're done. Supply an error as the first argument to callback to print a warning and cause the task to fail.

preferLocal

Type: boolean
Default: true

Execute local binaries by name like $ npm run-script.

execOptions

Type: object

Specify some options to be passed to the .exec() method:

  • cwd string Current working directory of the child process
  • env Object Environment key-value pairs
  • setsid boolean
  • encoding string (Default: 'utf8')
  • timeout number (Default: 0)
  • maxBuffer number (Default: 1000 * 1000 * 10 → 10 MB)
  • killSignal string (Default: 'SIGTERM')

Release Notes

4.0.0
By Sindre Sorhus • Published on March 19, 2022
3.0.1
By Sindre Sorhus • Published on December 27, 2018
  • Fix broken chalk upgrade 1361a33
3.0.0
By Sindre Sorhus • Published on December 22, 2018

Breaking:

  • Require Node.js >=6 and Grunt >=1 62cdda5

Other:

  • Allow functions as shorthand commands (#118) 86680b4
0.7.0
By Sindre Sorhus • Published on April 25, 2014

The options stdout, stderr and failOnError defaults changed from false to true to match user expectations.

General

License
MIT
Typescript Types
None found
Tree-shakeable
No

Popularity

GitHub Stargazers
952
Community Interest
1,141
Number of Forks
129

Maintenance

Commits
10/219/2202
Last Commit
Open Issues
2
Closed Issues
75
Open Pull Requests
0
Closed Pull Requests
28

Versions

Versions Released
10/219/2201
Latest Version Released
Mar 19, 2022
Current Tags
latest4.0.0

Dependencies

Dependencies (3)
Dev Dependencies (3)

Contributors

sindresorhus
sindresorhus
Commits: 76
thorn0
thorn0
Commits: 2
Richienb
Richienb
Commits: 1
teogeos
teogeos
Commits: 1
gingermusketeer
gingermusketeer
Commits: 1
pflannery
pflannery
Commits: 1
alippai
alippai
Commits: 1
DimitarChristoff
DimitarChristoff
Commits: 1
ksheedlo
ksheedlo
Commits: 1
mgoenka
mgoenka
Commits: 1
taavo
taavo
Commits: 1
tobek
tobek
Commits: 1
stevemao
stevemao
Commits: 1
ChrisWren
ChrisWren
Commits: 1
jbdeboer
jbdeboer
Commits: 1