Configuration

Configuration

stepshot runs fine with no config file at all — everything here is optional and only overrides the built-in defaults. A missing or malformed file falls back to defaults (with a warning on stderr); it never blocks startup.

Where it lives

$XDG_CONFIG_HOME/stepshot/config.toml, otherwise ~/.config/stepshot/config.toml (on Windows: %APPDATA%\stepshot\config.toml).

Write a commented starter file (it never overwrites an existing one):

stepshot --write-config

Options

[general]
# Base folder for sessions. A path given on the command line
# (`stepshot ~/some/dir`) still takes precedence over this.
# output_dir = "~/Pictures/stepshot"

[marker]
# The translucent click highlight drawn into each screenshot.
# fill = "#FFE13C"       # highlighter yellow
# fill_alpha = 0.35      # 0.0-1.0; low so text under it stays readable
# rim = "#FFA500"        # amber outline for contrast on light backgrounds
# rim_alpha = 0.75       # 0.0-1.0
# radius = 20.0          # marker size in pixels

[export]
# Which report formats to write. Default: all of them.
# formats = ["html", "md", "pdf", "docx", "odt", "rtf", "txt"]

[capture]
# Which mouse buttons create steps. Default: all three.
# buttons = ["left", "right", "middle"]
# Two clicks of the same button within this many milliseconds merge into one
# "double click" step. Set to 0 to disable merging. Default: 400.
# double_click_ms = 400

Notes:

• Colors are "#RRGGBB" (a leading # is optional); alpha is 0.0–1.0.
• output_dir understands a leading ~/ (your home).
• export.formats accepts html, md (or markdown), pdf, docx (or word), odt (or libreoffice/writer), rtf, and txt (or text/plain). Unknown names are ignored; an empty/all-invalid list falls back to all formats. The selection is honored both while recording and by stepshot edit/apply.
• capture.buttons accepts left, right, middle; unknown names are ignored and an all-invalid list falls back to all three. Clicks of a non-listed button are dropped (no step, no screenshot).
• capture.double_click_ms is the window for merging two rapid clicks of the same button into a single "double click" step (the first screenshot is kept). 0 records every click separately.
• The parser is a small TOML subset: [section] headers, key = value, strings/numbers/booleans/string-arrays, and full-line # comments (no inline comments).

Examples

Only ever write a self-contained HTML report, with a larger cyan marker:

[marker]
fill = "#20C0FF"
radius = 28

[export]
formats = ["html"]

PDF and DOCX only (e.g. for handing to non-technical colleagues):

[export]
formats = ["pdf", "docx"]