Skip to main content

captureSpawn

captureSpawn(command, args, options)​

Asynchronous function that captures the output of a spawned subprocess and renders an animated terminal screencast. Signature mimics that of child_process.spawn.

Returns a promise that resolves either a string if the output format option is 'svg', 'json', or 'yaml', or a Buffer if the output format is 'png'.

Arguments​

command​string

The command to run.

args​string[]

List of string arguments.

options​Object

A config object to specify the following common options, as well as the additional options listed in the next section.

Required
columns, rows
Terminal Related
tabSize, cursorHidden, windowTitle, windowIcon
Output Related
output, outputPath, scaleFactor, embedFonts, fonts
Capture Related
writeMergeThreshold, endTimePadding, cropStartDelay
Command Related
includeCommand, prompt, keystrokeAnimation, keystrokeAnimationInterval
Rendering Related
theme, fontFamily, fontSize, lineHeight, columnWidth, iconColumnWidth, borderRadius, boxShadow, offsetX, offsetY, paddingX, paddingY, decorations, insetMajor, insetMinor
Debugging
logLevel

Additional Options​

shell​boolean | string

Run the command inside of a shell. Default is false. If true, Unix will try to use the current shell (process.env.SHELL), falling back to /bin/sh if that fails, while Windows will try to use process.env.ComSpec, falling back to cmd.exe if that fails. Different shells can be specified using a string. The shell should understand the -c switch, or if the shell is cmd.exe, it should understand the /d /s /c switches.

cwd​string

Working directory to be set for the child process. Default is process.cwd().

env​Object

Environment key-value pairs to be set for the child process. Automatically extends from process.env, which can be changed by setting extendEnv to false. Default is undefined.

extendEnv​boolean

The child process environment extends from process.env. Defaults to true.

silent​boolean

Silently capture the spawned process' stdout and stderr output. If set to false, the output of the spawned process will be piped to process.stdout. Defaults to true.

connectStdin​boolean

Connect spawn to process.stdin to capture any input from the user. If the spawned process requires user input to complete, this option must be enabled, or the process will hang. Defaults to false.

warning

If connectStdin is enabled, the silent option must be set to false, or omitted.

timeout​number

The maximum amount of time the process is allowed to run in milliseconds. If greater than 0, the spawned process will be killed if it runs longer than the timeout milliseconds. Default is 0.

killSignal​string

The signal to be used when the spawned process is killed by timeout. Default is 'SIGTERM'.

useConptyWindows Only​boolean

Option passed to node-pty concerning whether to use ConPTY over winpty. If set to undefined, ConPTY will be used over winpty when the Windows build number is >= 18309. Defaults to false.

Usage​

Capturing a command​

Here is a basic example of capturing the output of the command echo Hello World!:

import { captureSpawn } from 'cli-screencast';

captureSpawn('echo', ['Hello World!'], {
    columns: 50,
    rows: 10,
    shell: process.platform === 'win32', // echo must be executed in a shell on Windows
    cursorHidden: true,
    includeCommand: false, // Don't include the command in output
}).then((svg) => {
    // Use or save the generated SVG string here
});
result
Hello World!

Capturing a command with a prompt​

Here is the same example as above, but with the includeCommand option enabled, which causes a command prompt with animated keystrokes to be included in the rendered capture.

import { captureSpawn } from 'cli-screencast';

captureSpawn('echo', ['Hello World!'], {
    columns: 50,
    rows: 10,
    shell: process.platform === 'win32', // echo must be executed in a shell on Windows
    cursorHidden: true,
    includeCommand: true, // Include the command in the output
}).then((svg) => {
    // Use or save the generated SVG string here
});
result
> > e> ec> ech> echo> echo > echo H> echo He> echo Hel> echo Hell> echo Hello> echo Hello > echo Hello W> echo Hello Wo> echo Hello Wor> echo Hello Worl> echo Hello World> echo Hello World!> echo Hello World!Hello World!

The keystrokeAnimationInterval option can be configured to customize the speed of the keystroke animation, or the prompt can be captured without the animation by disabling the keystrokeAnimation option. The prompt prefix can be customized via the prompt option.