Skip to content

For OSS maintainers

The problem: you maintain a tool with terminal screenshots in your README and docs. Every CLI change, every new feature, you remember to update some of the shots and forget the rest. Six months later half your docs lie about what your tool does.

The fix: define every screenshot once in shotty.toml, then shotty --render-all keeps them all in sync. (Or shotty --render <name> to redo just one.)

The workflow

  1. Drop a shotty.toml at your project root:

    snug = true          # default for all shots
font = "Menlo-Regular"

[[shot]]
output = "docs/images/help.png"
command = ["myapp", "--help"]

[[shot]]
output = "docs/images/install.png"
command = "brew install myapp 2>&1 | head -10"

[[shot]]
output = "docs/images/build.png"
command = "myapp build"
width = 100

    See the config schema for every key, and Configuration for how the project-local file interacts with the optional user-wide ~/.config/shotty/shotty.toml.

  2. Run:

    shotty --render-all

    Every [[shot]] is rendered. PNGs that decode to identical pixels are silently skipped — see Atomic writes & idempotency for why and how.

  3. Wire it into CI to fail when shots drift:

    shotty --render-all
git diff --exit-code docs/images/

    If git diff finds changes, your docs are out of date. CI fails, you regenerate locally, commit, push.

A real example

This site itself works that way. The shotty.toml at the project root defines every screenshot you've seen on these pages.

See also