Run a command, get a PNG that looks like your terminal. Works as a standalone CLI and as an MCP server for AI agents. Built for pentest reports, blog posts, and PR descriptions.
Highlights
Real ANSI rendering - colors, bold, italic, underline, Unicode, rendered
at 2x resolution with your own font. Commands run in a PTY through your login
shell, so your prompt, aliases, and PATH are in the image.
Redaction - opt-in masking of secrets in the image (--redact, or
auto = true in config). The text returned to the caller keeps the originals,
so an agent can inspect it and selectively redact.
See docs/redaction.md.
Themes - 11 built-in (using the bundled JetBrains Mono), plus any themes you
drop in ~/.config/termshot/themes/, each with its own fonts.
for; do
done
Your prompt, whatever it is - commands run through your login shell, so the
prompt in the image is the one your own shell config draws. Prompts are
independent of termshot themes, which only set colors, font, and background:
the four panes below are four different shell prompts in the one built-in
dark theme.
Starship, Powerlevel10k, Oh My Zsh themes, or a hand-rolled PS1 show up the
same way. The image uses isolated shell configs so it does not modify the
user's normal setup.
TERMSHOT_SHELL=/path/to/shell-wrapper
Chrome frames - title bar presets with optional timestamp. Good for reports and blog posts.
Composition - combine screenshots side by side or stacked (tmux-style) for before/after comparisons.
Full output, not the last screenful - --rows is the terminal viewport
(it decides where lines wrap), not a limit on what you see. Everything that
scrolls past is kept and rendered, so termshot exec --rows 10 'seq 1 200'
gives you all 200 lines. Narrow it with --head-lines N or --tail-lines N
when you only want one end; --head-lines is the first N lines of the output
however long the run turned out to be. Full-screen programs (vim, htop) are
the exception: they repaint the viewport, so only their active screen is
captured.
Accessible by default - every PNG embeds its terminal text (redacted, when
redaction ran) in a UTF-8 Description chunk so screen readers can read the
screenshot. Turn it off with --no-description or embed_description = false.
MCP server - four tools for agent workflows:
execute_and_screenshot, render_ansi, redact_screenshot,
compose_screenshots.
Install
# binary at ./target/release/termshot
Tagged releases also publish Linux (x86_64, aarch64, static musl) and macOS
(Intel, Apple Silicon) binaries plus .deb and .rpm packages.
Linux and macOS only: termshot uses PTYs and POSIX signals.
Usage
# render pre-captured ANSI without executing anything, from a file or a pipe
|
--rows/--cols set the terminal the command believes it is running in, which
is what makes long lines wrap the way they would on your screen. The screenshot
shows every line the command produced, including the ones that scrolled out of
that viewport, up to the max_scrollback_lines safety limit (10,000 by
default, and lower on a very wide terminal - see
docs/config.md). If a command overruns it, termshot says so
instead of quietly dropping the start, and a capture too tall to render fails
with an error pointing at --head-lines / --tail-lines.
--head-lines is not subject to that limit: it is captured as those lines
scroll past, so it is the first N lines of the output at any configured
capacity.
--redaction '<JSON>' masks something the built-in rules do not know about.
It is repeatable, applies in the order given, and takes exactly the
specifications the MCP redact_screenshot tool takes - a regex pattern or an
explicit cell range of the rendered screenshot:
Passing it redacts the screenshot even without --redact (add --redact to
run the built-in rules as well), and it conflicts with --no-redact rather
than being silently ignored. The MCP execute_and_screenshot and render_ansi
tools take the same specifications inline, as a redactions array. See
docs/redaction.md.
Tips
MCP server
Add to your MCP client config:
Docs
- docs/mcp.md - MCP setup, tool reference, agent workflows
- docs/themes.md - built-in and user themes, fonts, fallback
- docs/redaction.md - rules, custom rules, partial redaction
- docs/config.md -
config.tomlreference