Config schema¶

This page is the schema reference for shotty.toml: every key, its TOML type, and its default. For where shotty looks for the file and how the local + user-wide configs interact, see Configuration.

Anatomy¶

# Top-level keys = defaults applied to every shot below.
width = 100
font = "Menlo-Regular"
snug = true

# Each [[shot]] is a render target. `output` and `command` are
# required; everything else can override a top-level default.
[[shot]]
output = "docs/images/ls.png"
command = "ls -la | head -8"           # string → shell mode

[[shot]]
output = "docs/images/help.png"
command = ["myapp", "--help"]          # array → exec mode
title = "myapp --help"
width = 80

Bulk regeneration¶

shotty --render-all          # every shot
shotty --render hero         # one shot, by name

--render-all renders every [[shot]] in the active config; --render <name> resolves a single one (matching output exactly, then by basename, then by basename-without-extension). Each PNG is rendered into memory, compared pixel-for-pixel with the existing file (decoded back to RGBA), and only re-written if it's actually different. The atomic rename doesn't happen for unchanged shots, so:

file watchers (fswatch, entr, dev servers) stay quiet
Git's working tree stays clean
ReadTheDocs and similar build systems don't see spurious changes

Resolution order¶

For each option, the effective value is determined top-down:

Per-shot override (highest priority)
Top-level default in the same config
Hardcoded default

CLI flags override everything when running ad-hoc commands (shotty "cmd" or shotty -- cmd).

Command forms¶

command = "ls -la" (string): Single shell command line. Run via sh -c, gets a green ❯ prompt header above the output. Same as shotty "ls -la".
command = ["ls", "-la"] (array of strings): Pre-tokenized argv, exec'd directly. No shell, no prompt header. Same as shotty -- ls -la. Use this for multi-line scripts where you don't want the source code as a prompt header.

The TOML syntax — string vs array — chooses the form. Same key either way.

Available keys¶

All keys are optional except where noted. They can appear at the top level (as defaults) and/or inside any [[shot]] (as overrides).

Key	TOML type	Default	Meaning
`output`	string	—	Required for shots. Output PNG path.
`command`	string or array of strings	—	Required for shots. A string is a shell command line (`sh -c`, prompt header rendered); an array is exec'd directly with no shell or header.
`width`	int	`80`	Terminal columns.
`height`	int	`24`	Terminal rows the child sees as `LINES`. Kept small so full-screen TUIs (`vim`, `htop`, `less`) render at a normal size.
`max_height`	int	`120`	Cap on the snug-mode scrollback. When `snug` is on, the grid can grow taller than `height` as scrolling output accumulates, up to this many rows; past the cap, scrolling drops the top row as a real terminal would.
`font`	string	`"Menlo-Regular"`	Monospace font PostScript name.
`font_size`	number	`13`	Font point size.
`line_height`	number	`1.0`	Line-height multiplier.
`title`	string	the command	Window title text. The empty string `""` hides the title bar text.
`shadow`	bool	`true`	Drop shadow under the window. Set `false` to disable.
`margin`	number	`36`	Outer margin in points.
`scale`	number	`2`	Pixel scale factor.
`snug`	bool	`true`	Trim trailing blanks and preserve scrollback above `height` (up to `max_height`) when scrolling output accumulates. Set to `false` for the literal `width × height` grid with classic drop-top scrolling.
`timeout`	number	(none)	SIGKILL child after N seconds.
`embed_command`	bool	`false`	Embed the command in the PNG's `UserComment` metadata so the shot can be reproduced from the file alone. Off by default — commands can contain paths or other things you might not want in a published image.
`style`	string	—	(per-shot only) Name of a `[styles.<name>]` to apply.
`default_style`	string	—	(top-level only) Name of a style applied to every shot that doesn't set its own.
`[styles.<name>]`	table	—	(top-level only) A reusable bundle of visual keys: `width`, `height`, `max_height`, `font`, `font_size`, `line_height`, `margin`, `scale`, `snug`, `shadow`, `title`. See Configuration.

Numeric flexibility

TOML distinguishes 8 (int) from 8.0 (float) but Shotty accepts either for any numeric field. Write whichever feels natural.

A real example¶

The shotty.toml at the root of this repo defines every screenshot on this site. Browse it for working examples of the two command forms, per-shot font overrides, multi-line printf scripts, the meta inline-image shot, and more.