Module visual-exec

visual-exec

Run a shell command and show it as a live spinner line instead of a wall of output.

Output is captured while the command runs and the terminal shows a single updating line; on failure the captured output is logged so you can see what went wrong. The default logger detects CI and turns the in-place items off there, so build logs stay plain. Built on visual-logger and xsh.

Install

npm install visual-exec

Usage

import VisualExec from "visual-exec";

const ve = new VisualExec({
  command: "npm install",
  cwd: "/path/to/project",
  displayTitle: "installing dependencies"
});

const { stdout, stderr } = await ve.execute();

API

See the full API reference for every option, type, and runtime rule.

`new VisualExec(options)`

Command

option	description
`command`	the command to run (required)
`cwd`	working directory
`maxBuffer`	max stdout/stderr buffer, default 10MB

Display

option	description
`displayTitle`	text shown on the spinner line while running
`logLabel` / `outputLabel`	labels used in log and output messages
`outputLevel`	log level for captured output, default `verbose`
`visualLogger`	a visual-logger instance to log through
`spinner`	spinner style

Failure handling

option	description
`forceStderr`	log stderr as error, default true
`checkStdoutError`	boolean or regex - treat matching stdout as an error, default true

Cancellation

option	description
`timeout`	milliseconds before the process is killed
`timeoutGrace`	ms between SIGTERM and SIGKILL, default 5000
`onTimeout`	called just before killing
`signal`	an `AbortSignal` to cancel with

Consuming output

option	description
`onOutput(data, stream)`	called on each stdout/stderr chunk
`onComplete(output, exitCode)`	called when finished; its return value becomes `execute()`'s result on success
`outputFile` / `outputFileOptions`	stream output to a file (`append`, `includeStderr`, `timestamps`)
`progress` / `onProgress`	extract progress from stdout or stderr by regex or custom function
`progress.format(p)`	text to show after the `stdout` label, ie: `p => \`${p.current}/${p.total}``
`matchers`	`[{ pattern, onMatch }]` run against output lines

Methods

execute(command?) - run it; resolves to { stdout, stderr }, or to onComplete's return value when one is given
abort() / kill(signal?) - stop a running command