Skip to main content

captureShell

captureShell(options)​

Asynchronous function that captures a shell session and then renders it as an animated terminal screencast. A new shell session will be spawned and piped to process.stdout and process.stdin, then you interact with the shell until it is exited or you press Ctrl+D.

tip

The shell session recording can be stopped with Ctrl+D.

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:​

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
Rendering Related
theme, fontFamily, fontSize, lineHeight, columnWidth, iconColumnWidth, borderRadius, boxShadow, offsetX, offsetY, paddingX, paddingY, decorations, insetMajor, insetMinor
Debugging
logLevel

Additional Options​

shell​string

The shell to run. If unspecified, Unix will try to use the current shell (process.env.SHELL), falling back to /bin/sh if that fails. Windows will try to use process.env.ComSpec, falling back to cmd.exe if that fails.

cwd​string

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

env​Object

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

extendEnv​boolean

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

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​

Here is a basic example of a script that spawns and captures a new shell process. It will run powershell on windows or zsh in unix like environments, and the shell will start from the user's home directory. The rendered screencast svg is written to a file called capture.svg in the current working directory using the outputPath option.

Below is an example execution that captures a zsh shell process where the user runs the command echo Hello World! and then exits the shell.

capture.js
#!/usr/bin/env node
import { homedir } from 'os';
import { captureShell } from 'cli-screencast';

captureShell({
    // Use PowerShell on Windows, Zsh on Unix-based OS
    shell: process.platform === 'win32' ? 'pwsh.exe' : 'zsh',
    // Start shell session from the user's home directory
    cwd: homedir(),
    columns: 50,
    rows: 10,
    // Customize cursor appearance
    theme: { cursorStyle: 'underline', cursorBlink: true },
    // Save output SVG to a file in the directory this script is run in
    outputPath: './capture.svg',
});
Example script execution:
~  examples ~  examples n ~  examples no ~  examples nod ~  examples node ~  examples node ~  examples node c ~  examples node ca ~  examples node cap ~  examples node capt ~  examples node captu ~  examples node captur ~  examples node capture ~  examples node capture. ~  examples node capture.j ~  examples node capture.js ~  examples node capture.js>>> ● Capture Start >>> ~  examples node capture.js>>> ● Capture Start >>> ~ ~  examples node capture.js>>> ● Capture Start >>> ~ e ~  examples node capture.js>>> ● Capture Start >>> ~ ec ~  examples node capture.js>>> ● Capture Start >>> ~ ech ~  examples node capture.js>>> ● Capture Start >>> ~ echo ~  examples node capture.js>>> ● Capture Start >>> ~ echo ~  examples node capture.js>>> ● Capture Start >>> ~ echo H ~  examples node capture.js>>> ● Capture Start >>> ~ echo He ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hel ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hell ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello W ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello Wo ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello Wor ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello Worl ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello World ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello World! ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello World!Hello World! ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello World!Hello World! ~ ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello World!Hello World! ~ e ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello World!Hello World! ~ ex ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello World!Hello World! ~ exi ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello World!Hello World! ~ exit ~  examples node capture.js>>> ● Capture Start >>> ~ echo Hello World!Hello World! ~ exit<<< ■ Capture End <<<
resultcapture.svg
~ ~ 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! ~ echo Hello World!Hello World! ~ ~ echo Hello World!Hello World! ~ e ~ echo Hello World!Hello World! ~ ex ~ echo Hello World!Hello World! ~ exi ~ echo Hello World!Hello World! ~ exit