KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#dsh #ai-agents #dsh-plugin #codex #developer-tools #claude-code #windows #desktop-app #typescript #rust #ai-agent #cli

executive

★ 37 Open GitHub ↗

🕴Elegant command execution for Node.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# executive

[![npm][npm-img]][npm-url]
[![build][build-img]][build-url]
[![dependencies][dependencies-img]][dependencies-url]
[![downloads][downloads-img]][downloads-url]
[![license][license-img]][license-url]
[![chat][chat-img]][chat-url]

> An elegant `child_process.spawn`

Executive is simple and intuitive interface to
[`child_process.spawn`][child_process] with zero depdencies. Built-in support
for async and sync process creation, built-in flow control and automatic shell
make working with external processes in Node easy.

## Features
- Async callback, promise and sync APIs
- Automatically pipes `stderr` and `stdout` by default
- Automatically uses shell when commands use builtins, globs or operators
- Built-in control flow with support for parallel and serial execution
- Mix simple string commands with functions and promises returning commands
- Multi-line strings parsed as multiple commands and executed sequentially
- Streams `stderr` and `stdout` rather than blocking on command completion
- Included TypeScript type definition
- Improved Windows support
- No external dependencies

## Install
```bash
$ npm install executive --save-dev
```

## Usage

No need to echo as `stderr` and `stdout` are piped by default.

```javascript
import exec from 'executive'

exec('uglifyjs foo.js --compress --mangle > foo.min.js')
```

It's easy to be quiet too.
```javascript
exec.quiet('uglifyjs foo.js --compress --mangle > foo.min.js')
```

Callbacks and promises are both supported.
```javascript
exec('ls', (err, stdout, stderr) => console.log(stdout))
exec('ls').then(res => console.log(res.stdout))
```

Automatically serializes commands.

```javascript
exec(['ls', 'ls', 'ls']) // All three ls commands will be executed in order

exec(`ls -l
      ls -lh
      ls -lha`) // Also executed in order
```

Want to execute your commands in parallel? No problem.
```javascript
exec.parallel(['ls', 'ls', 'ls'])
```

Want to collect individual results? Easy.
```javascript
{a, b, c} = await exec.parallel({
  a: 'echo a',
  b: 'echo b',
  c: 'echo c'
})
```

Want to blend in Promises or pure functions? You got it.
```javascript
exec.parallel([
  'ls',

// Promises can be blended directly in
  exec('ls'),

// Promises returned by functions are automatically consumed
  () => exec('ls'),

// Functions which return a string are assumed to be commands
  () => 'ls',

// Functions and promises can return objects with stdout, stderr or status
  () => ({ stdout: 'huzzah', stderr: '', status: 0 }),

'ls'
])

```

## Options
Options are passed as the second argument to exec. Helper methods for
`quiet`, `interactive`, `parallel` and `sync` do what you expect.

```javascript
exec('ls', { quiet: true })
```

and

```javascript
exec.quiet('ls')
```

are equivalent.

#### options.interactive | exec.interactive
##### default `false`

If you need to interact with a program (your favorite text editor for instance)
or watch the output of a long running process (`tail -f`), or just don't care
about checking `stderr` and `stdout`, set `interactive` to `true`:

```javascript
exec.interactive('vim', err => {
  // Edit your commit message
})
```

#### options.quiet | exec.quiet
##### default `false`

If you'd prefer not to pipe `stdout` and `stderr` set `quiet` to `true`:

```javascript
exec.quiet(['ls', 'ls'], (err, stdout, stderr) => {
  // You can still inspect stdout, stderr of course
})
```

#### options.sync | exec.sync
##### default `false`
Blocking version of exec. Returns `{stdout, stderr}` or throws an error.

#### options.parallel | exec.parallel
##### default `false`
Uses parallel rather than serial execution of commands.

#### options.shell
##### default `null`
Force a shell to be used for command execution.

#### options.strict
##### default `false`
Any non-zero exit status is treated as an error. Promises will be rejected and
an error will be thrown with `exec.sync` if `syncThrows` is enabled.

#### options.syncThrows
##### default `false`
Will cause `exec.sync` to throw errors rather than returning them.

## Extra
Great with `sake`, `grunt`, `gulp` and other task runners. Even nicer with
`async` and `await`.

Fancy example using [`sake`](http://github.com/sakejs/sake-cli):

```javascript
task('package', 'Package project', => {
  // Create dist folder
  await exec(`
    mkdir -p dist/
    rm   -rf dist/*
  `)

// Copy assets to dist in parallel
  await exec.parallel(`
    cp manifest.json dist/
    cp -rf assets/   dist/
    cp -rf lib/      dist/
    cp -rf views/    dist/
  `)

// Get current git commit hash
  let {stdout} = await exec('git rev-parse HEAD')
  let hash     = stdout.substring(0, 8)

# Zip up dist
  exec(`zip -r package-${hash}.zip dist/`)
})
```

You can find more usage examples in the [tests](test/test.coffee).

## License
[MIT][license-url]

[child_process]:    https://nodejs.org/api/child_process.html

[build-img]:        https://img.shields.io/travis/zeekay/executive.svg
[build-url]:        https://travis-ci.org/zeekay/executive
[chat-img]:         https://badges.gitter.im/join-chat.svg
[chat-url]:         https://gitter.im/zeekay/hi
[coverage-img]:     https://coveralls.io/repos/zeekay/executive/badge.svg?branch=master&service=github
[coverage-url]:     https://coveralls.io/github/zeekay/executive?branch=master
[dependencies-img]: https://david-dm.org/zeekay/executive.svg
[dependencies-url]: https://david-dm.org/zeekay/executive
[downloads-img]:    https://img.shields.io/npm/dm/executive.svg
[downloads-url]:    http://badge.fury.io/js/executive
[license-img]:      https://img.shields.io/npm/l/executive.svg
[license-url]:      https://github.com/zeekay/executive/blob/master/LICENSE
[npm-img]:          https://img.shields.io/npm/v/executive.svg
[npm-url]:          https://www.npmjs.com/package/executive

executive

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README