cli-shot📦 Library API
Using capture(), listScreens(), toImage(), shootScreen(), and shootAll() programmatically instead of via the binary.
@kud/cli-shot is a library first — the cli-shot binary is a thin commander wrapper around the same functions it exports. Import them directly when you need to shoot from Node instead of a shell.
import {
shootAll,
shootScreen,
capture,
listScreens,
toImage,
} from "@kud/cli-shot"shootAll(options)
Shoots every screen the driven CLI reports via --screen list, writing one PNG per screen, and returns the list of paths written.
const written = await shootAll({
command: "pcloud",
out: "assets/screenshots",
})shootScreen(screen, options)
Shoots a single named screen and returns the path written.
const path = await shootScreen("sync", {
command: "pcloud",
out: "shots",
})Both take a ShootOptions object:
| option | |
|---|---|
command | the CLI to drive |
args | arguments passed before the ones cli-shot adds (--mock, --screen <name>) |
out | directory the PNGs are written to |
mock | drive from fixtures — defaults to true |
cols / rows | terminal size |
settle | ms of silence that counts as finished drawing |
timeout | hard limit before the child is killed regardless |
env | extra environment variables for the child process |
keys | keystrokes sent once the first draw has settled |
freezeArgs | extra flags passed straight to freeze, e.g. ["--theme", "nord"] |
listScreens(command, args?)
Runs command with --screen list appended and returns the screen names as a string array, one per line of stdout, trimmed and with blanks filtered out. This is the discovery step both shootAll and the --list CLI flag use — see The contract.
capture(command, args?, options?)
The lower-level primitive: spawns command in a pty, feeds the output through a headless @xterm terminal, waits for it to settle, and resolves with the serialised ANSI for the final screen — without writing an image. Useful if you want the ANSI yourself rather than a PNG. Defaults to cols: 110, rows: 32, settle: 800, timeout: 15_000 — the same values the CLI binary uses, so a library call and a cli-shot run produce the same image.
toImage(ansi, output, options?)
Pipes ANSI text into freeze over stdin and writes a PNG to output, creating any missing parent directories. options.freezeArgs passes extra flags straight through to freeze. Requires freeze on PATH (brew install charmbracelet/tap/freeze).