Interface: Shell

shell.Shell

Interactive shell session created by createShell. Extends EventEmitter so you can use on / once / off / removeListener, etc.

Inheritance

• EventEmitter

  ↳ Shell

Table of contents

Methods

• exec
• exit
• submit

Events

• on

Methods

exec

exec(cmd): Promise<ExecutionResult>

Run cmd in this session and wait for the process to finish.

Example

"nodejs";
const { createShell } = require("shell");
async function main() {
  const shell = createShell();
  console.log(await shell.exec("touch test.txt"));
  console.log(await shell.exec("ls -l test.txt"));
  await shell.exit();
}
main();

Parameters

Name	Type	Description
cmd	string	Full command line to execute.

Returns

Promise<ExecutionResult>

Resolves with exit code and captured streams.

---

exit

exit(forcedly?): Promise<ExitResult>

Tears down the shell process.

• forcedly === true — kill the process immediately; resolves to a string signal name when applicable.
• forcedly === false (default) — send a normal exit command and resolve with the numeric exit code.

Parameters

Name	Type	Description
forcedly?	boolean	Force-kill vs cooperative exit.

Returns

Promise<ExitResult>

---

submit

submit(input): void

Writes input to the shell’s stdin. A trailing newline is appended automatically if you omit one.

Parameters

Name	Type
input	string

Returns

void

Events

on

on(event, listener): Shell

Subscribe to streamed output. Supported event names:

• "data" — raw Buffer chunks as they arrive.
• "line" — newline-delimited string rows (without the \n).

Example

"nodejs";
const { createShell } = require("shell");

const shell = createShell();

shell.on("data", (chunk, type) => {
  console.log(`${type} chunk:`, chunk.toString());
});

shell.on("line", (line, type) => {
  console.log(`${type} line:`, line);
});

shell.exec("ls -la");

"data" event

Fires whenever stdout or stderr produces more bytes.

Example

"nodejs";
const { createShell } = require("shell");

const shell = createShell();
shell.on("data", (chunk, type) => {
  if (type === "stdout") {
    console.log("stdout:", chunk.toString());
  } else if (type === "stderr") {
    console.error("stderr:", chunk.toString());
  }
});
shell.exec("echo 'Hello' && echo 'Error' >&2");

Parameters ("data")

Name	Type	Description
event	"data"	Literal event name "data".
listener	(chunk: Buffer, type: StandardOutputType) => void	chunk is the raw bytes; type is "stdout" or "stderr".

Returns

Shell — this for chaining.

---

"line" event

Fires once per completed text line on stdout or stderr.

Example

"nodejs";
const { createShell } = require("shell");

const shell = createShell();
shell.on("line", (line, type) => {
  if (type === "stdout") {
    console.log("stdout line:", line);
  } else if (type === "stderr") {
    console.error("stderr line:", line);
  }
});
shell.exec("ls -1");

Parameters ("line")

Name	Type	Description
event	"line"	Literal event name "line".
listener	(line: string, type: StandardOutputType) => void	line excludes the newline; type is "stdout" or "stderr".

Returns

Shell — this for chaining.