Automate Screenshots on Mac with the Command Line

Every Mac includes screencapture, the command behind the system screenshot shortcuts. Called from a zsh loop, it takes timed screenshots of the full screen or a fixed area with no extra software. This post builds the loop one piece at a time, adds page turns, and lists the fixes for the failures that come up most often.

Check permission before debugging the command

screencapture runs with the permissions of the app that launched it. In Terminal, that means Terminal needs screen recording permission. Without it, the command still succeeds, but the image shows only the wallpaper and menu bar.

Open System Settings, then Privacy and Security, and turn on your terminal app (Terminal, iTerm or another) in the screen recording list. The exact label varies by macOS version. Quit and reopen the terminal app after the change.

Take one screenshot from Terminal

Start with a single capture before writing any loop:

screencapture -x ~/Desktop/test.png
open ~/Desktop/test.png

The -x flag turns off the shutter sound. If the image shows your open windows, permission and paths are working. Run man screencapture to see every flag your macOS version supports.

Capture the full screen every few seconds

This loop takes 20 captures, 3 seconds apart, into a new folder named after the start time:

#!/bin/zsh
out=~/Captures/run-$(date +%Y%m%d-%H%M%S)
mkdir -p "$out"

for i in {1..20}; do
  screencapture -x -m "$out/frame-$(printf %04d $i).png"
  sleep 3
done
echo "Saved 20 frames to $out"

Zero-padded names (frame-0001.png) keep the files in capture order in Finder and in any tool that sorts by name. The -m flag limits the capture to the main display. Without it, a Mac with two displays expects one file name per display. Use -D 2 to capture the secondary display instead.

Save the script as capture.sh, run chmod +x capture.sh, then ./capture.sh. Press Control+C to stop early. Frames already saved stay in the folder.

Capture one fixed area repeatedly

Add -R x,y,w,h to capture a rectangle. Values are in points, measured from the top-left corner of the main display:

screencapture -x -R 200,120,1200,800 "$out/frame-$(printf %04d $i).png"

To find the coordinates, press Shift+Command+4 and watch the numbers next to the crosshair at the top-left and bottom-right corners of the area. Width is the right edge minus the left edge, and height is the bottom edge minus the top edge.

A fixed rectangle does not follow a window. If the window moves or the display layout changes during the run, later frames capture the wrong area.

Save JPG files instead of PNG

Use -t jpg and change the extension:

screencapture -x -t jpg "$out/frame-$(printf %04d $i).jpg"

PNG keeps text edges sharp and is the safer default for interfaces. JPG files are smaller, which matters for runs with hundreds of frames. The command also accepts pdf and tiff.

Press a key between screenshots without overshooting

Paging through slides or a reader needs a key press after each capture. osascript sends one through System Events. Key code 124 is Right Arrow:

pages=30
for i in {1..$pages}; do
  screencapture -x -m "$out/page-$(printf %04d $i).png"
  if (( i < pages )); then
    osascript -e 'tell application "System Events" to key code 124'
    sleep 1.5
  fi
done

Three details prevent missed or extra pages. The capture runs first, so the starting page is saved. The if skips the key press after the last capture, so the reader does not move past the final page. The sleep after the key gives the next page time to render before the next capture.

System Events sends keys to the frontmost app, so click the reader window before the loop starts, or add a sleep 5 at the top to switch apps. Terminal needs Accessibility permission for key events.

Keep a long run awake

If the display sleeps, frames come out black. Wrap the script in caffeinate, which holds a sleep assertion for as long as the script runs:

caffeinate -di ./capture.sh

The -d flag keeps the display awake and -i prevents idle sleep. Closing the lid or locking the screen still interrupts the run.

Troubleshoot a failed screencapture loop

Symptom	Cause	Fix
Only wallpaper and menu bar	No screen recording permission	Allow the terminal app, then reopen it
"No such file or directory"	Output folder missing	Run mkdir -p before the loop
Two images or an error per capture	Several displays, one file name	Add -m or -D 1
Black frames	Display slept	Run the script with caffeinate -di
Pages skipped	Key sent before the page rendered	Increase the sleep after the key
Key presses ignored	Missing Accessibility permission or wrong app in front	Allow the terminal app, click the target window

When a script is no longer the easy option

A shell loop suits a fixed job that runs the same way every time. Each new requirement adds code: stopping at a clock time, pausing and resuming, picking a window by name (the -l flag needs a window ID that macOS does not list for you), or producing a searchable PDF.

Temposhot's Auto Capture turns those into settings. You pick Screens, Windows or Custom Area from thumbnails, set Screenshots, Duration or End time as the stop condition, and record any key in the Key press field. A floating toolbar pauses, resumes and finishes the run. Exports cover PNG, JPG, ZIP, searchable PDF and MP4.

FAQ

Where does screencapture save files?

It saves to the path you pass as the last argument. With -c it copies the image to the clipboard instead.

Can screencapture include the cursor?

Yes. Add -C to include the pointer. It works only in non-interactive captures, which covers every command in this post.

How do I add a delay before the first capture?

Use -T 5 for a 5-second delay on a single capture, or put sleep 5 before the loop.

Can I turn the frames into a PDF or video?

Yes. Image to PDF combines the frames into one PDF in name order, and Images to Video turns them into a video. Both run in the browser and keep files on your Mac.

Turn repeatable screenshots into finished work

When the script grows past a fixed region and a fixed count, try Auto Capture instead. The automated capture guide covers every option, and the download page has the Apple Silicon build.