kud/cli-shot

<div align="center"

📸 cli-shot

<img src="https://img.shields.io/npm/v/@kud/cli-shot?style=flat-square" alt="npm version" / <img src="https://img.shields.io/badge/licence-MIT-blue?style=flat-square" alt="MIT licence" / <img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square" alt="Node =20" /

Automatic screenshots of interactive CLIs — pty capture, terminal emulation, PNG out.

Website · Documentation · npm

</div

Point it at a CLI. It asks which screens the CLI has, opens each one, and writes an image per screen. No per-project script, no keystroke tables, no hand-cropped window captures that go stale the next time the UI moves.

Features

• Screens discovered, not hardcoded — asks the CLI via --screen list, so a tab you add shows up in the next run without touching this package
• Real terminal emulation — the pty stream is resolved to the grid a user would see, rather than every redraw concatenated
• Fixtures by default — --mock is on unless you opt out, because a screenshot outlives the moment it was taken
• Deterministic and headless — fixed size, fixed data, no window manager, runnable in CI
• Scriptable last mile — --keys reaches state a screen name can't address

Install

npm install --global @kud/cli-shot
brew install charmbracelet/tap/freeze   # the renderer

Usage

cli-shot --out assets/screenshots -- pcloud

Everything after -- is the command being driven, so its own flags stay clear of cli-shot's.

cli-shot adds --mock and --screen to that command, but only where you haven't. Anything you pass wins:

cli-shot --out shots -- pcloud --screen sync    # shoots Sync, writes sync.png
cli-shot --out shots --only sync -- pcloud      # the same thing, said from here

Naming a screen yourself is already an answer to "which one", so cli-shot skips the discovery loop and takes the filename from your value.

cli-shot --out shots --only sync -- pcloud        # one screen
cli-shot --out shots --list -- pcloud             # what screens exist
cli-shot --out shots --keys $'jjj\r' -- pcloud    # drive deeper first
cli-shot --out shots --no-mock -- pcloud          # real data (careful)