# shellbee
Latest version **0.5.30** (published 2025-08-08) · MIT license · 0 weekly downloads
## Install
```sh
npm install shellbee
pnpm add shellbee
yarn add shellbee
bun add shellbee
```
Provides the command `shellbee`.
## Health
**Score 35/100 (D)** — status: maintenance-mode.
Positive: has types; no vulnerabilities; high quality score.
Warnings: low downloads; no esm support; pre 1.0.
Negative: stale; low maintenance score.
## Facts
| | |
|---|---|
| Version | 0.5.30 |
| Published | 2025-08-08 |
| First published | 2020-02-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 310.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Alex Kit |
| Maintainers | tenbits |
## Links
- npm: https://www.npmjs.com/package/shellbee
- npm.io page: https://npm.io/package/shellbee
## Dependencies (5)
- [alot](https://npm.io/package/alot.md) ^0.3.3
- [ruta](https://npm.io/package/ruta.md) ^0.2.71
- [atma-io](https://npm.io/package/atma-io.md) ^1.2.65
- [tree-kill](https://npm.io/package/tree-kill.md) ^1.2.2
- [atma-utils](https://npm.io/package/atma-utils.md) ^0.2.60
## Recent versions
- 0.5.30 (latest) — 2025-08-08
- 0.5.29 — 2023-04-07
- 0.5.28 — 2022-12-12
- 0.5.26 — 2022-09-13
- 0.5.25 — 2022-09-13
- 0.5.24 — 2022-08-08
- 0.5.23 — 2022-08-07
- 0.5.22 — 2022-03-23
- 0.5.21 — 2022-03-17
- 0.5.20 — 2022-03-11
- 0.5.18 — 2022-03-09
- 0.5.17 — 2021-12-27
- 0.5.16 — 2021-10-01
- 0.5.15 — 2021-10-01
- 0.5.14 — 2021-06-15
- … 11 more at https://npm.io/package/shellbee/versions
## README
# Shellbee
----
> Yet another shell command executor (**cmd**, **bash**) and NodeJS fork with Inter Process Communication (IPC).
----
[](https://dl.circleci.com/status-badge/redirect/gh/atmajs/shellbee/tree/master)
[](http://badge.fury.io/js/shellbee)
```ts
import { Shell } from 'shellbee'
// executes commmands and waits until they exit
let shell: Shell = await Shell.run(command: string | string[] | IShellParams);
// instatiate the new shell instance, attach all required event listeners, etc, and later call `run` to start executing
let shell = new Shell({ command: `git commit -am "foo"` });
interface IShellParams {
command?: string | IProcessSingleParams
commands?: (string | IProcessSingleParams)[]
detached?: boolean
cwd?: string
/** Watches the output and emits ready event when the child process prints expected text to the std */
matchReady?: RegExp
silent?: boolean
parallel?: boolean
// command should container js file to fork
fork?: boolean
// Defines if a child_process supports IPC
ipc?: boolean
timeoutsMs?: number
restartOnErrorExit?: boolean
}
interface IProcessSingleParams {
command: string
cwd?: string
detached?: boolean
matchReady?: RegExp
extract: {[ key: string ]: (output: string) => any }
}
interface IShell {
commands: ICommandOptions[]
results = [] as ProcessResult[]
std: string[] = [];
stderr: string[] = [];
stdout: string[] = [];
start: Date
end: Date
busy: boolean
/** Resolves after the all commands are settled */
promise: Promise
run (): Promise
kill()
onStart (cb: (data: { command: string }) => void): this
onStdout (cb: (data: { command: string, buffer: string }) => void): this
onStderr (cb: (data: { command: string, buffer: string }) => void): this
onExit (cb: (data: { command: string, code: number, result: ProcessResult }) => void): this
/** When rgxReady is specified the event will be called */
onReady (cb: ({ command: string }) => void): this
onComplete(cb: (shell: Shell) => void): this
}
```
## Communication channel
#### Basic Configuration
```ts
// main.js
import { Shell } from 'shellbee'
let shell = new Shell({
command: 'bar.js',
fork: true,
ipc: true
})
shell.run();
let result = await shell.send('doFoo', { foo: 1 });
```
```ts
// bar.js
import { Shell } from 'shellbee'
Shell.ipc({
doFoo (...args) {
console.log(args);
return 'lorem';
}
});
```
#### Advanced Configuration
1. Fork a process as usual.
```js
let shell = new Shell({ command: 'bar.js', fork: true });
shell.run();
```
2. In the worker listen for a message
```ts
{
id: string,
method: string
args: any[]
}
```
The child process should process the work and sends a message with the `id` and result back to parent process:
```ts
{
id: string,
data?: any,
error?: Error
}
```
Simple Forked file example:
```js
// worker.js
process.on('message', async (message: { id, method, args }) => {
let result = await MyWorker.doWork(message.method, ...message.args);
process.send({
id: message.id,
data: result,
error: null
});
});
```
### CLI
Execute a CLI task and makes sure it restarts on error or when output got stalled. For example you want to run a script from npm scripts forever, e.g. "npm run foo"
```bash
shellbee run npm run foo
--delay
--restart
--restart-window
--stalled-output
```
- `dalay` - Milliseconds before the process is started again
- `restart` - Amount of restarts within a time window. For example if the process has been crashed for 10 times within 30 seconds, do not restart any more.
- `restart-window` - Milliseconds, a time-frame to count crashes in, when to many crashes occur (defined by `restart`) `shellbee` stops restarting the process.
- `stalled-output` - Milliseconds, if the process has no output (`stdout`, `stderr`) for this time, then we assume the process has stopped responding, so `shellbee` will restart it
---
---
_Source: https://npm.io/package/shellbee · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._