Skip to content

Latest commit

 

History

History
105 lines (75 loc) · 3.01 KB

README.md

File metadata and controls

105 lines (75 loc) · 3.01 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
    • Array of unescaped strings. Cannot contain shell logic. Recommended for portability.
    • A string. Executed as a shell statement. Please take care when escaping input.
  • options - Optional. More info.
  • callback - Optional. Called on success/failure. Receives the statusCode. Implies the async:true option.
  • statusCode - 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
    • Array of unescaped strings. Cannot contain shell logic. Recommended for portability.
    • A string. Executed as a shell statement. Please take care when escaping input.
  • options: Optional. More info.
  • promise: 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.