CMD Promise

Node command line interface with a simple Promise based API.

Inspired by node-cmd.

Features

• Simple Promise based API.
• Single or multiple commands in one call.
• Passes the exec() node options through.
• Returns an object containing both stdout and stderr.
• Optionally return the child process instead of the output.
• Zero dependencies.

Requirments

Uses native node promises (including Promise.all with generic iterables) so requires at least node version 4.0.0. See http://node.green/.

Install

npm install cmd-promise

Examples

Single command

const cmd = require('cmd-promise')

cmd(`node -v`).then(out => {
  console.log('out =', out)
}).catch(err => {
  console.log('err =', err)
})

// out = { stdout: 'v4.2.2\r\n', stderr: '' }

Multiple commands

const cmd = require('cmd-promise')

const commands = `
  node -v
  npm -v
`

cmd(commands).then(out => {
  console.log('out =', out)
}).catch(err => {
  console.log('err =', err)
})

// out = [ { stdout: 'v4.2.2\r\n', stderr: '' }, { stdout: '4.4.1\n', stderr: '' } ]
// out[0].stdout = v4.2.2

More involved example

const semver = require('semver') // https://github.com/npm/node-semver
const cmd = require('cmd-promise')

const commands = `
  npm view npm version
  npm -v
`

cmd(commands).then(out => {
  return {
    npm: out[0].stdout.replace(/\n/g, ''),
    me: out[1].stdout.replace(/\n/g, '')
  }
}).then(versions => {
  if (semver.lt(versions.me, versions.npm)) {
    console.log(`My npm version is out of date (npm install npm@latest -g).`)
  } else {
    console.log(`My npm version is up to date! :-)`)
  }
}).catch(err => {
  console.log('err =', err)
})

Return the child process instead

const cmd = require('../cmd-promise')

const options = { returnProcess: true }

cmd(`node -v`, options).then(childProcess => {
  console.log('pid =', childProcess.pid)
  childProcess.stdout.on('data', stdout => {
    console.log('stdout =', stdout)
  })
  childProcess.stderr.on('data', stderr => {
    console.log('stderr =', stderr)
  })
}).catch(err => {
  console.log('err =', err)
})

Pass exec() options

Pass child_process.exec() options as defined in the node docs.

const cmd = require('../cmd-promise')

const execOptions = { timeout: 1000 }

cmd(`node -v`, {}, execOptions).then(out => {
  console.log('out =', out)
}).catch(err => {
  console.log('err =', err)
})

API

cmd(commands [,options] [,execOptions]) -> Promise

• commands (string) Single or multiple line string of commands to execute.
• options (object)
  • returnProcess (boolean) Return the child process instead of waiting on and returning the outcome. Default is false.
• execOptions (object) Options as passed to the exec() method of the child_process node module.

Returns a Promise.

For single commands the promises return value is an object containing stdout and stderr properties. If options.returnProcess is set to true the return value is the child process instead.

const cmd = require('cmd-promise')

cmd(`node -v`).then(out => {
  console.log('out.stdout =', out.stdout) // v4.2.2
  console.log('out.stderr =', out.stderr)
})

For multiple line command calls the promises return value is an array of object's containing stdout and stderr properties. If options.returnProcess is set to true the return value is an array of child processes instead.

const cmd = require('cmd-promise')

const commands = `
  node -v
  npm -v
`

cmd(commands).then(out => {
  console.log('out[0] =', out[0]) // result from 'node -v'
  console.log('out[1] =', out[1]) // result from 'npm -v'
})