Take website screenshots from the command line

The quickest way to screenshot a website from a terminal is to send the URL to a screenshot API and save what comes back. The browser runs on the API’s servers, so all you need locally is curl, with no Chrome, Puppeteer, or missing system libraries to deal with.

This guide uses Bash and curl on macOS or Linux. Everything also works in WSL on Windows. If you want to run the browser on your own machine instead, see the Puppeteer screenshot guide.

One URL, one command

Get a ScreenshotOne access key, export it as SCREENSHOTONE_ACCESS_KEY, and run:

1
curl --fail --silent --show-error --max-time 120 --get \
2
  'https://api.screenshotone.com/take' \
3
  --header "X-Access-Key: ${SCREENSHOTONE_ACCESS_KEY:?Set the access key first}" \
4
  --data-urlencode 'url=https://example.com/' \
5
  --data-urlencode 'format=png' \
6
  --data-urlencode 'full_page=true' \
7
  --data-urlencode 'viewport_width=1280' \
8
  --data-urlencode 'viewport_height=800' \
9
  --output example.png

That’s it. example.png is your screenshot. The response is the image itself, with no JSON to parse.

A few of these flags matter more than they look:

• --data-urlencode encodes the target URL correctly even if it has its own ?a=1&b=2 query string.
• The single quotes stop your shell from treating & as “run in background.”
• --fail makes HTTP errors return a non-zero exit code. Without it, curl happily saves the error response as example.png, and you find out later.

A reusable script that won’t overwrite good captures

For repeat runs, you want one more property: if a capture fails, keep the last good image. This script downloads to a temporary file and only replaces the real one once the result looks valid. Save it as capture-one.sh:

1
#!/usr/bin/env bash
2
set -euo pipefail
3

4
: "${SCREENSHOTONE_ACCESS_KEY:?Set SCREENSHOTONE_ACCESS_KEY}"
5
if [[ $# -lt 1 || $# -gt 2 ]]; then
6
  printf 'Usage: bash capture-one.sh URL [output.png]\n' >&2
7
  exit 2
8
fi
9

10
target_url=$1
11
output_path=${2:-screenshot.png}
12

13
mkdir -p -- "$(dirname -- "$output_path")"
14
temporary_path=$(mktemp "${output_path}.tmp.XXXXXX")
15
trap 'rm -f -- "$temporary_path"' EXIT
16

17
content_type=$(curl --fail --silent --show-error --max-time 120 --get \
18
  'https://api.screenshotone.com/take' \
19
  --header "X-Access-Key: $SCREENSHOTONE_ACCESS_KEY" \
20
  --data-urlencode "url=$target_url" \
21
  --data-urlencode 'format=png' \
22
  --data-urlencode 'full_page=true' \
23
  --data-urlencode 'viewport_width=1280' \
24
  --data-urlencode 'viewport_height=800' \
25
  --output "$temporary_path" \
26
  --write-out '%{content_type}')
27

28
if [[ $content_type != image/png* || ! -s $temporary_path ]]; then
29
  printf 'Did not get a PNG back; kept the existing file.\n' >&2
30
  exit 1
31
fi
32

33
mv -f -- "$temporary_path" "$output_path"
34
printf 'Saved %s\n' "$output_path"

Run it with a quoted URL:

1
bash capture-one.sh 'https://example.com/?category=design&sort=new' captures/example.png

Two notes on the capture settings:

• The viewport width picks the layout. full_page=true only makes the image taller. It won’t give you the desktop layout on its own, so set the width you actually want.
• Full-page captures scroll the page first so lazy-loaded images have a chance to appear. If some are still missing, increase the scroll delay. See the full-page options.

A list of URLs

Put one URL per line in urls.txt. Lines starting with # are ignored:

1
https://example.com/
2
https://example.org/
3
# Add the public pages you want to capture.

Save this as capture-list.sh, next to capture-one.sh:

1
#!/usr/bin/env bash
2
set -euo pipefail
3

4
input_file=${1:-urls.txt}
5
output_dir=${2:-captures}
6
script_dir=$(cd -- "$(dirname -- "$0")" && pwd)
7
mkdir -p -- "$output_dir"
8
manifest="$output_dir/results.tsv"
9
printf 'file\tstatus\turl\n' > "$manifest"
10

11
number=0
12
failures=0
13
while IFS= read -r target_url || [[ -n "$target_url" ]]; do
14
  target_url=${target_url%$'\r'}
15
  [[ -z "$target_url" || "$target_url" == \#* ]] && continue
16
  number=$((number + 1))
17
  filename=$(printf '%04d.png' "$number")
18
  if bash "$script_dir/capture-one.sh" "$target_url" "$output_dir/$filename"; then
19
    status=ok
20
  else
21
    status=failed
22
    failures=$((failures + 1))
23
  fi
24
  printf '%s\t%s\t%s\n' "$filename" "$status" "$target_url" >> "$manifest"
25
done < "$input_file"
26

27
if [[ $number -eq 0 ]]; then
28
  printf 'No URLs found in %s.\n' "$input_file" >&2
29
  exit 2
30
fi
31
printf 'Captured %s URLs, %s failed.\n' "$number" "$failures"
32
[[ $failures -eq 0 ]]

Run it into a timestamped folder so runs don’t mix:

1
bash capture-list.sh urls.txt "captures/$(date -u +%Y%m%dT%H%M%SZ)"

A failed URL doesn’t stop the run. It’s marked failed in results.tsv, the other URLs continue, and the script exits non-zero at the end so cron or CI notices. Use results.tsv to see which file belongs to which URL rather than going by the file names.

The script processes URLs one at a time, which is fine for dozens of URLs. For thousands, check your plan’s concurrency limit, run a few in parallel (for example with xargs -P), and add retries with backoff.

Run it on a schedule

The API takes the screenshots, and something else decides when. That can be cron, systemd timers, or a CI service you already use. With cron on Linux:

1
0 8 * * * /bin/bash /opt/site-captures/run-daily.sh >> /opt/site-captures/capture.log 2>&1

And run-daily.sh:

1
#!/usr/bin/env bash
2
set -euo pipefail
3
cd /opt/site-captures
4
# Keep the key in a file only this user can read, outside version control.
5
source /opt/site-captures/access-key.env
6
export SCREENSHOTONE_ACCESS_KEY
7
bash capture-list.sh urls.txt "captures/$(date -u +%Y%m%dT%H%M%SZ)"

Cron catches a lot of people out because it runs with a minimal environment: a short PATH, no shell profile, and the server’s time zone. Use absolute paths, and run the wrapper manually once before you rely on the schedule.

If a run could take longer than the gap between runs, wrap it in flock so two don’t overlap. Make sure failures reach you as alerts. Nobody reads capture.log until something has already gone wrong.

For captures alongside a deployment review, the GitHub Actions screenshot guide shows how to capture deployed routes and save the images as workflow artifacts.

Or use the ScreenshotOne CLI

If you’d rather have named commands than curl flags, install the ScreenshotOne CLI. It’s also available as a Docker image (see the CLI integration page). Once your keys are configured:

1
screenshotone take 'https://example.com/' -o viewport.png
2
screenshotone full-page 'https://example.com/' --full-page-scroll -o full-page.png
3
screenshotone pdf 'https://example.com/' --pdf-print-background -o document.pdf

The CLI signs its requests, so follow its README to set both the access key and the secret key. One gotcha: its --json flag prints the signed request URL. It doesn’t ask the API for JSON metadata the way response_type=json does.

When it doesn’t work

My advice: get one URL looking right, then roll the same settings out to the list. A 200 OK only means the API returned an image. You still need to look at it to know the page rendered the way you wanted.