Skip to content

Latest commit

 

History

History
105 lines (75 loc) · 3.28 KB

README.md

File metadata and controls

105 lines (75 loc) · 3.28 KB
Raw

shelljs-live

Execute a shell command while piping output directly to your console.

Motivated by shelljs exec's inability to preserve colors. Also, great for watcher tasks, as output is not buffered.

Very portable (uses cross-spawn), especially when specifying command as an array of strings (more below).

Installation

npm install shelljs shelljs-live

The shelljs package is a peerDependency of shelljs-live and must be installed.

Traditional API

live(command [, options] [, callback]) => statusCode
  • command - A string OR an array of strings:
    • If a string, run as a shell statement. The shell might expand globs or have opinions about escaping. This is not very portable.
    • If an array of strings, all arguments are piped directly to a command and no escaping is necessary. This is recommended.
  • options - Optional. More info.
  • callback - Optional. Called on success/failure. Receives the statusCode. Implies the async:true option.
  • statusCode - A number, or in some cases null. Success means statusCode === 0.

Synchronous usage:

const { live } = require('shelljs-live')

const statusCode = live(['ps', '-ax']) // live('ps -ax') works too. not recommended
if (statusCode === 0) {
  console.log('Success')
} else {
  console.log('Failure')
}

Asynchronous usage:

const { live } = require('shelljs-live')

live(['ps', '-ax'], (statusCode) => {
  if (statusCode === 0) {
    console.log('Success')
  } else {
    console.log('Failure')
  }
})

Promise API

live(command [, options]) => promise
  • command: A string OR an array of strings:
    • If a string, run as a shell statement. The shell might expand globs or have opinions about escaping. This is not very portable.
    • If an array of strings, all arguments are piped directly to a command and no escaping is necessary. This is recommended.
  • options: Optional. More info.
  • promise: A Promise that triggers success when status code equals 0, failure otherwise. Neither handler receives the status code.

Usage:

const { live } = require('shelljs-live/promise')

live(['ps', '-ax']).then(() => {
  console.log('Success')
}, () => {
  console.log('Failure')
})

Or if you want to use await and don't care about handling errors:

const { live } = require('shelljs-live/promise')

await live(['ps', '-ax'])
console.log('Success')

Options

  • async: Asynchronous execution. If a callback is provided, or using the Promise API, it will be set to true, regardless of the passed value (default: false).
  • fatal: Exit upon error (default: false, inherits from ShellJS Config).
  • silent: Do not echo program output to console (default: false, inherits from ShellJS Config).

Any other option, such as cwd, is passed directly to spawn.