Skip to content

Basic usage

The flags you'll reach for in your first hour. See the CLI reference for the complete list.

Two invocation forms

Form What it does
shotty "ls -la \| head" Single positional → run via sh -c. A green ❯ + the command line is rendered above the output.
shotty -- ls -la Everything after -- is the literal argv for execvp. No shell, no prompt header.

Use the first form for one-off interactive-feeling shots, the second when you've already tokenized the command or don't want the prompt banner (especially for multi-line scripts where the source itself would clutter the header).

Where it goes

shotty -o release-notes.png "git log --oneline -10"

-o / --output overrides the default timestamped filename. Files are written atomically (temp + rename), and Shotty refuses to overwrite anything that isn't already a PNG — see Atomic writes for the full story.

Sizing the terminal

shotty --width 100 --height 30 "tree -L 2"

Default size is 80 × 24. The child process always sees --height rows as its terminal — kept small so full-screen TUIs (vim, htop, less) render at a normal size. With --snug on (the default), tall scrolling output (a long git log, the --demo sampler) is preserved above the visible window as scrollback up to --max-height rows (default 120), so the screenshot can be much taller than 24 rows without anything dropping off the top. Pass --no-snug to fall back to the literal width × height grid with classic drop-top scrolling.

Window title

Defaults to the command line — usually fine. Override when you want something tidier:

shotty --title "build" -- cargo build

--no-title hides the text entirely (the traffic-light buttons stay).

Pick a font

The default is Menlo at 13pt. Anything from shotty --list-fonts works:

shotty --font CascadiaCode-Regular --font-size 14 \
    "bat --color=always --paging=never main.swift"

--line-height N (default 1.0) is a multiplier — try 1.2–1.4 for more vertical breathing room.

For Carbon/ray.so-style code shots paired with bat or another syntax highlighter, see Code screenshots.

Strip the chrome

For embedding inside a slide or hero image where the macOS window frame would distract:

shotty --no-title --no-shadow --margin 0 "echo 'just the grid'"

High-DPI

Default --scale 2 is retina. 3 for print or 4K work; 1 for thumbnails or smaller files:

shotty --scale 3 "uname -a && sw_vers"

Where to next