terminal-screenshot

name

terminal-screenshot

description

Capture a CLI's real terminal output and render it as an SVG for a README or docs page. Use when asked to add a screenshot, demo, or example output to a README, when a project's README shows fabricated or placeholder output that should be replaced with a real run, or when documenting any command-line tool. Also use before publishing a CLI repo, since a terminal image is the single highest-impact thing a CLI README can have.

Terminal screenshots for READMEs

A CLI README lives or dies on whether a reader can see the tool working within two seconds of landing. A fenced code block is fine; an image of the real output is better, and it is what makes a repo look finished.

This skill uses runshot to run a command, capture what it actually printed including colour, and render it as an SVG.

It is not on npm. Clone https://github.com/daronthedragon/runshot, run npm install && npm run build && npm link, and runshot is on PATH. Never npx runshot - that unscoped name is an unrelated package.

The one rule

Never fabricate output. Run the tool and capture what it really printed.

Invented sample output is the most common failure here and the most damaging: it looks plausible, it survives review, and it is wrong the moment anyone runs the thing. If the tool cannot produce real output yet — missing API key, no test data, not implemented — say so and stop. Do not compose a realistic looking block and present it as a run.

If the output legitimately needs a stand-in address, key, or path, use one and label the image as illustrative. That is honest. A fabricated result is not.

Usage

runshot --title mytool -- mytool --demo

Common flags:

Flag	Use
--title <text>	Label in the window chrome. Usually the tool name.
--prompt <text>	Prepends a fake prompt line so it reads as a session, e.g. $ mytool status
--cwd <path>	Run the command somewhere else. Use this instead of embedding cd.
--max-lines <n>	Trim long output. 20-25 lines is the sweet spot for a README.
--text <path>	Also write the plain-text version, for a fallback block.
--theme light	For docs sites with a light background. Default dark suits both GitHub themes.
--stream stdout	When progress chatter on stderr would clutter the image.

Recommended README pattern

Image first, with the plain text tucked behind a disclosure so it stays copy-pasteable and reachable for screen readers and anyone the image fails for:

<p align="center">
  <img src="assets/demo.svg" width="720" alt="Terminal session showing ...">
</p>

<details>
<summary>Same output as text</summary>

...contents of the --text file...

</details>

Write a real alt describing what the output shows, not "screenshot".

Generate both files in one command so they can never drift apart:

runshot --title mytool --max-lines 22 \
  -o assets/demo.svg --text assets/demo.txt -- mytool --demo

Getting colour out of the program

runshot sets FORCE_COLOR, CLICOLOR_FORCE, COLORTERM and TERM, which covers chalk, picocolors, colorette, supports-color and most Rust and Go CLIs.

If the capture comes out monochrome, the program is checking isatty directly and ignoring those variables. Options, in order of preference:

1. Check for a flag the tool already has (--color=always is common).
2. Capture through a pty yourself and pass the file to runshot --input.
3. Accept monochrome. It still beats a fabricated block.

Checks before committing

• Look at the file. Open the SVG. Do not push an image you have not seen.
• Does anything clip? Every line is pinned with textLength, so the canvas fits by construction — but confirm nothing was truncated by --max-lines mid-sentence.
• Any secrets? Real runs print real data. Scan for API keys, tokens, internal hostnames, personal addresses and email. Regenerate with redacted input rather than editing the SVG by hand.
• Is the claim in the README still true? If the caption says "real output", it must be from a real run of the current code.

When a screenshot is the wrong answer

• Output that is one or two lines. Use a code block.
• Output that changes every run in ways that matter (timestamps, live prices). Either accept it as a point-in-time snapshot and say so, or use a code block.
• Interactive TUIs. A static frame misrepresents them; record a GIF instead.