| name | screenshot-cli |
| description | Use when the user's host screen must be captured — the full desktop, one monitor, or a pixel region — or when a screen capture needs cropping, resizing, rotation, flipping, format conversion (png/jpeg/webp), quality control, or filters/enhancement; also when you need to enumerate connected monitors and their geometry. Not for browser-page screenshots (use claude-in-chrome). |
Screenshot CLI
One-command screen capture plus post-processing via screenshot.py in this
directory (PEP 723 script, mss + Pillow; uv run handles dependencies, no
setup). Prefer it over screencapture + sips: screencapture -R takes
Retina points (2x pixel surprise) and sips --cropOffset silently
center-crops. This CLI uses one consistent unit — whatever --list-monitors
reports — verified: -r 100,100,800,600 yields an 800x600 image.
Quick start
screenshot.py ships alongside this SKILL.md — set S to its path inside
this skill's directory (the base directory reported when the skill loads):
S=<this-skill-dir>/screenshot.py
uv run $S --list-monitors
uv run $S -m 1 -o shot.png
uv run $S -m 1 -r 100,100,800,600 -f jpeg -q 70 --resize 50% -o region.jpg
Flags
| Group | Flags |
|---|
| capture | -m N monitor (0 = all, 1..N single) · -r X,Y,W,H region, relative to the selected monitor's origin · --list-monitors |
| output | -o PATH (default screenshot-<timestamp>.<ext> in cwd) · -f {png,jpeg,webp,bmp,tiff} (default: inferred from -o extension, else png) · -q 1-100 (jpeg/webp only) · --lossless (webp) |
| geometry | --crop X,Y,W,H · --roll DX,DY (wraparound shift) · --rotate DEG · --flip-h · --flip-v · --resize 1200x800 | 1200x | x800 | 50% |
| enhance | --filter NAME (repeatable: blur, sharpen, smooth, smooth-more, detail, contour, edge-enhance, edge-enhance-more, emboss, find-edges) · --blur RADIUS · --brightness/--contrast/--saturation/--sharpness F (1.0 = unchanged; the full PIL ImageEnhance module — Brightness, Contrast, Color, Sharpness) · --grayscale · --invert · --autocontrast |
Behavior contract
- Processing order: crop → roll → rotate → flip → resize → filters → enhance.
- Success prints
path (WxH, FORMAT, KB) to stdout, exit 0. Bad input prints a
one-line error: ... to stderr, exits nonzero — safe to branch on exit code.
- A region extending past the monitor is clipped with a stderr warning.
--rotate expands the canvas (black fill), so output dims can exceed input.
Gotchas
-q is silently ignored for png/bmp/tiff.--list-monitors reports geometry only. To identify which index is the
built-in display, cross-reference system_profiler SPDisplaysDataType -json
(match resolutions); indices can change when displays are replugged.--help is complete and authoritative for anything not listed here.
