termshot 1.1.1

Terminal screenshot CLI and MCP server with ANSI rendering, redaction, themes, and composition
Documentation

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.

termshot exec --chrome gnome --title 'termshot - ls src/' 'ls --color=always -la src/'

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.

termshot exec 'git log --graph --oneline --color=always -n 6'

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.

termshot exec --redact --chrome gnome 'command cat .env.staging'

Themes - 11 built-in (using the bundled JetBrains Mono), plus any themes you drop in ~/.config/termshot/themes/, each with its own fonts.

for theme in catppuccin-mocha dracula nord; do
  termshot exec --theme "$theme" --no-rounded -o "$theme.png" \
    'git log --oneline --color=always -n 4'
done
termshot compose --divider 4 -o themes.png \
  catppuccin-mocha.png dracula.png nord.png

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 termshot exec \
  --theme dark -o prompt.png 'git status -sb'
termshot compose --divider 4 -o prompts.png prompt-*.png

Chrome frames - title bar presets with optional timestamp. Good for reports and blog posts.

termshot exec --chrome gnome --timestamp 'nmap -F localhost'

Composition - combine screenshots side by side or stacked (tmux-style) for before/after comparisons.

termshot exec -o before.png 'git status -su'
git add -A
termshot exec -o after.png 'git status -su'
termshot compose --layout horizontal --chrome gnome \
  --title 'git status - before / after staging' -o compose.png before.png after.png

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.

termshot exec 'cargo build 2>&1'               # every line, however long
termshot exec --tail-lines 20 'cargo test'     # just the summary
termshot exec --head-lines 15 'dmesg'          # just the top

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

git clone https://github.com/Adamkadaban/screenshot-mcp termshot
cd termshot
cargo build --release
# 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

termshot exec 'ls --color=always -la'                          # basic screenshot
termshot exec --chrome gnome --theme dracula 'git log'         # chrome + theme
termshot exec --redact 'cat credentials.txt'                   # mask secrets
termshot exec --redaction '{"pattern":"AKIA[0-9A-Z]{16}","keep_prefix":4}' \
  'cat credentials.txt'                                        # mask your own pattern
termshot exec --no-rounded 'ls --color=always'                 # square corners
termshot exec --tail-lines 20 'cargo test'                     # last 20 lines
termshot exec --head-lines 20 'dmesg'                          # first 20 lines
termshot compose -o diff.png before.png after.png              # stack two shots
termshot themes                                                # list themes

# render pre-captured ANSI without executing anything, from a file or a pipe
cmd --color=always | termshot render -
termshot render output.log --redact
termshot render --tail-lines 30 build.log

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

termshot exec \
  --redaction '{"pattern":"[a-f0-9]{32}","replacement":"HASH","keep_prefix":4}' \
  'secretsdump.py corp.local/user@10.20.30.40'

termshot render --redaction '{"row":3,"col_start":12,"col_end":44,"label":"SECRET"}' \
  capture.ansi

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

termshot exec '!!'                            # your shell expands !! first
termshot exec 'command cat .env.staging'      # bypass a cat -> bat alias
termshot exec --no-prompt 'cat .env.staging'  # no prompt, no aliases
termshot exec --redact --redaction '{"pattern":"TCK-[0-9]+","replacement":"TICKET"}' \
  'cat notes.txt'                             # built-in rules plus your own
alias tshot='termshot exec'

MCP server

Add to your MCP client config:

{
  "mcpServers": {
    "termshot": {
      "command": "/path/to/termshot",
      "args": ["mcp"]
    }
  }
}

Docs

License

MIT