1.0.1 • Published 8 years ago

node-run-cmd v1.0.1

Weekly downloads
11,015
License
MIT
Repository
github
Last release
8 years ago

node-run-cmd

- Node.js commandline/terminal interface.

Easily run simple or sophisticated console/terminal command(s) from Node. Supports sequential and parallel execution. Returns a promise that resolves to an array of exit codes for each command run.

With node-run-cmd you can execute a single command or an array of commands quite simply.

If you want, set in-depth options for commands being run, including callbacks for data, errors, and completion. Also set working directory, environment variables, run execution process in detached mode, set the uid and gid for the execution process(es), and set the shell to run the command in.

The source that this package is based on has been in production since February, 2016. Note that the examples here are for illustrative purposes only; most of the time there is no real need to run commands from Node, and they should be avoided if there are cross-platform requirements. This package aims to help when there isn't an agreeable alternative.

If most of your commands are filesystem related, I would instead look to node-fs-extra to accomplish what the commands would have.

NPM:

node-cmd npm version supported node version for node-cmd total npm downloads for node-cmd monthly npm downloads for node-cmd npm licence for node-cmd

GitHub:

node-run-cmd GitHub Release GitHub license node-run-cmd license open issues for node-run-cmd on GitHub

Licensed via MIT License.

-

Quick Start

The quickest way to get started is to run a single, simple command, then increase complexity as needed.

Install the package:

$ npm install --save node-run-cmd

Use the package:

var nrc = require('node-run-cmd');
nrc.run('mkdir foo');

Examples

These examples get increasingly complex to demonstrate the robustness of the package. Not all options are demonstrated; see the Options Object section for all possible options.

Simple command

nrc.run('mkdir foo');

Aysnchronous usage

Promise style

nrc.run('mkdir foo').then(function(exitCodes) {
  doSomethingElse();
}, function(err) {
  console.log('Command failed to run with error: ', err);
});

Callback style

var callback = function (exitCodes) {
  doSomethingElse();
};
nrc.run('mkdir foo', { onDone: callback } );

Use output (stdout) from command

var dataCallback = function(data) {
  useData(data);
};
nrc.run('ls', { onData: dataCallback });

Use error output (stderr) from command

var errorCallback = function(data) {
  useErrorData(data);
};
nrc.run('ls ~/does/not/exist', { onError: dataCallback });

Use exit code from command

var doneCallback = function(code) {
  useCode(code);
};
nrc.run('ls foo', { onDone: doneCallback });

OR

nrc.run('ls foo').then(function(codes){ useCode(codes[0]); });

Run multiple commands

nrc.run([ 'mkdir foo', 'touch foo/bar.txt' ]);

Set working directory for commands

var commands = [
  'mkdir foo',
  'touch foo/bar.txt'
];
var options = { cwd: 'path/to/my/dir' };
nrc.run(commands, options);

Set different working directory for each command

var commands = [
  { command: 'mkdir foo', cwd: 'dir1' },
  { command: 'mkdir foo', cwd: 'dir2' }
];
nrc.run(commands);

Set different working directory one command and default working directory for the others

var commands = [
  'mkdir foo',
  { command: 'mkdir foo', cwd: 'different/dir' },
  'mkdir bar'
];
var options = { cwd: 'default/dir' };
nrc.run(commands, options);

Run commands in parallel

var commands = [
  './runCompute1.sh',
  './runCompute2.sh',
  './runCompute3.sh',
];
var options = { mode: 'parallel' };
nrc.run(commands, options);

NRC Methods

Run

Usage:

var promise = nrc.run(commands, globalOptions);

Returns:

A promise that resolves to an array of exit codes for commands run.

Arguments:

commands can be specified in any one of the below formats

nametyperequireddescriptionexample
commandsstringyesThe command to run'ls'
commandsarray(string)yesAn array of string commands to run['ls', 'mkdir foo']
commandsarray(object)yesAn array of objects describing commands to run. See section Options Object for allowed properties.[{ command: 'ls' }, { command: 'mkdir foo' }]
commandsarray(object or string)yesA mixed array of objects describing commands and string commands to run. See section Options Object for allowed properties.[{ command: 'ls' }, 'mkdir foo']
globalOptionsobjectnoThe global options to set for each command being run. Overridden by command's options.{ cwd: 'foo', verbose: true, logger: gutil.log }

Options Object

Options available for the commands or globalOptions argument:

propertytyperequireddefaultdescription
commandstringyes-the command to run
cwdstringnoprocess.cwd()the directory to run the command in
onDatafunction(data)nonullwhere to send output from stdout. Called each time stdout is written.
onErrorfunction(data)nonullwhere to send output from stderr. Called each time stderr is written.
onDonefunction(code)nonullwhere to send the exit code of the command. Called once.
verbosebooleannofalseshow verbose output
loggerfunction(data)noconsole.logwhat function to use to log when verbose is set to true
envobjectnonullEnvironment key-value pairs
stdiostring or arraynonullChild's stdio configuration
detachedbooleannonullPrepare child to run independently of its parent process. Specific behavior depends on the platform.
uidnumbernonullSets the user identity of the process.
gidnumbernonullSets the group identity of the process.
shellboolean or stringnonullIf true, runs command inside of a shell. Uses '/bin/sh' on UNIX, and 'cmd.exe' on Windows. A different shell can be specified as a string. The shell should understand the -c switch on UNIX, or /s /c on Windows. Defaults to false (no shell).

Global-Only Commands

These options can only be set in the globalOptions argument.

propertytyperequireddefaultdescription
modestringno'sequential'Whether to run commands in series (sequentially) or in parallel.