CLI Tools

One command. One URL. Your screenshot.
In a pipeline, in a Makefile, or right at your prompt.

~/projects · shotbot

$ shotbot capture --url=https://www.shotbot.net
✓ captured in 2s
✓ saved www.shotbot.net-ab1c2d3e.jpg (412 KB)
$ _

Same flags. Same exit codes. Same config shape.
Switch from PHP to Python or Node.js without rewriting your scripts.

The CLI itself is in English, on every system. Each client stores its API key and defaults in its own ~/.shotbot-<lang>-cli/config.json | the three can coexist without stepping on each other.

Zero runtime dependencies. No Composer.
PHP, Python and Node.js | each a single file, open source, MIT licensed. Pick whichever runtime you already have.

Install

Python | pip

pip install shotbot

Node.js | npm

npm install -g shotbot

PHP | curl | requires PHP 8.0+ and php-curl

curl -fsSL https://api.shotbot.net/cli/php/shotbot -o shotbot \
  && chmod +x shotbot \
  && sudo mv shotbot /usr/local/bin/

Python | curl | requires Python 3.8+, zero dependencies

curl -fsSL https://api.shotbot.net/cli/python/shotbot -o shotbot \
  && chmod +x shotbot \
  && sudo mv shotbot /usr/local/bin/

Node.js | curl | requires Node.js 18+, zero dependencies

curl -fsSL https://api.shotbot.net/cli/node/shotbot -o shotbot \
  && chmod +x shotbot \
  && sudo mv shotbot /usr/local/bin/

To put it on your $PATH: sudo mv shotbot /usr/local/bin/. On first run the CLI prompts for your API key and stores it under ~/.shotbot-<lang>-cli/config.json (one config dir per client, chmod 600), so the three can coexist.

Available clients

PHP current version: 0.3.0

PHP 8.0+ and php-curl. Linux, macOS, BSD, Windows (via WSL or native PHP).

Download

Python current version: 0.3.0

Python 3.8+, stdlib only. Linux, macOS, BSD, Windows (if Python is installed).

Download

Node.js current version: 0.3.0

Node.js 18+, no third-party deps (uses built-in fetch). Linux, macOS, BSD, Windows (if Node is installed).

Download

First capture

basic capture (saves a file in the current directory)

shotbot capture --url=https://www.shotbot.net/

choose the filename or directory

shotbot capture --url=https://www.shotbot.net/ --output=screenshot.jpg

full page, PDF format

shotbot capture --url=https://www.shotbot.net/ --full-page --format=pdf

grab the JSON token for downstream processing

shotbot capture --url=https://www.shotbot.net/ --json | jq .token

Private by default

Every CLI capture is private and saved to the current directory unless you ask otherwise. The result is never published on the CDN: it lives in a non-public area server-side, the CLI downloads it for you, and the server copy is purged automatically after a short retention window. Add --cdn for a permanent public URL (no local file).

Private by default is handy for sensitive pages (intranets, dashboards, customer data). See the FAQ for the technical details.

Capture options

Free account

Option	Values	Default
`--url`	http(s) URL, required	\|
`--format`	`jpg` \| `png` \| `webp` \| `avif` \| `pdf`	`jpg`
`--viewport`	390/768/1280 (free) \| 280-3840 (Pro)	`1280`
`--output-size`	120..1920 px (resize the result)	viewport
`--wait`	0..30 seconds after page load	`5`
`--ratio`	`16:9`, `4:3`, `1:1`, `9:16`, etc.	`16:9`
`--full-page`	flag (capture full page)	off
`--nojs`	flag (disable JavaScript)	off
`--color-scheme`	`dark` \| `light`	\|
`--hidpi`	flag (DPR ×2, Retina)	off

Shotbot Pro

Option	Values
`--dismiss-cookies`	`accept` \| `reject` (auto-handle cookie banners)
`--scroll`	flag (scroll before capture, lazy-load trigger)
`--block-ads`	flag (block ad-network requests)
`--crop-height`	10..20000 px (crops height, overrides `--ratio`)
`--selector`	CSS selector (capture only the matched element)
`--http-auth-user` / `--http-auth-pass`	HTTP Basic auth credentials
`--option render_region=X`	`fr-paris` (default) \| `ca-montreal` \| `sg-singapore` \| `au-sydney` \| `vn-hanoi` \| geolocated screenshots

The CLI does no client-side gating: eligibility is enforced by the API. Without Shotbot Pro, these options return 403 pro_required and the CLI exits with code 4.

PDF (only with `--format=pdf`)

Option	Values	Default
`--pdf-page-size`	`A4`, `A3`, `A5`, `Letter`, `Legal`, `Tabloid`	`A4`
`--pdf-margin`	0..50 mm	`10`
`--pdf-scale`	0.10..2.00	`1.00`
`--pdf-landscape`	landscape orientation	off

CLI options

Option	Description
`--output[=PATH]`	Choose where to save (default: cwd, auto-named `host-token.jpg`). Trailing `/`: save into that directory, auto-named. Otherwise: exact destination path.
`--cdn`	Publish to the public CDN and return a permanent URL (no local file). Without it, captures stay private and are saved locally (see above).
`--json`	Print the full API response as JSON (no file saved).
`--timeout=N`	Max polling wait in seconds (default: 180).

Persistent defaults

Configure once, capture without retyping flags. Per-call flags always win over defaults.

save your preferences

shotbot set viewport 1440         # always 1440 px
shotbot set full-page             # always full page
shotbot set output ./shots/       # always save into ./shots/
shotbot set cdn true              # always publish to the public CDN
shotbot set format webp           # always WebP

shotbot defaults                  # show what is stored
shotbot defaults --keys           # list every settable key
shotbot unset full-page           # forget that default

Defaults live in the same ~/.shotbot-<lang>-cli/config.json as the API key.

Using in CI/CD | GitHub Actions, GitLab CI, Makefile

Pass SHOTBOT_API_KEY as an environment variable to skip the interactive prompt, set NO_COLOR=1 for ANSI-free output, and check the exit code | code 5 (quota / waitlist) is not a hard failure.

github actions / gitlab ci / bash

export SHOTBOT_API_KEY="$SHOTBOT_KEY"   # skips the interactive prompt
export NO_COLOR=1                       # disables ANSI colors

shotbot capture \
  --url=https://staging.example.com \
  --viewport=1440 --full-page \
  --output=artifacts/staging.jpg \
  --timeout=120

case $? in
  0) echo "OK" ;;
  5) echo "Quota exhausted"; exit 0 ;;     # waitlisted, not a hard failure
  *) echo "Capture failed (code $?)"; exit 1 ;;
esac

Environment variables

Variable	Effect
`SHOTBOT_API_KEY`	Override the stored key. Required in CI.
`SHOTBOT_API_BASE`	Override the base URL (default `https://api.shotbot.net`).
`NO_COLOR`	Disable ANSI color output.

Exit codes

Code	Meaning
`0`	Success.
`2`	Bad invocation (missing args, invalid config).
`3`	Network error.
`4`	API returned an error (invalid key, Pro option without Pro, refused URL…).
`5`	Waitlisted (monthly quota exhausted).
`6`	Server-side capture failure (target unreachable, browser crash).
`7`	Polling timeout (use `--timeout=N`).

Other commands

Command	Effect
`shotbot status [--json]`	Show account plan, credits, monthly quota and captures in flight. `--json` prints raw JSON.
`shotbot set <key> [value]`	Persist a default.
`shotbot unset <key>`	Remove a default.
`shotbot defaults [--keys]`	List defaults or settable keys.
`shotbot config`	Print the path to the config file.
`shotbot reset`	Clear the saved API key.
`shotbot version`	Print the version.
`shotbot help`	Print full help.

CLI Tools

Install

Available clients

PHP current version: 0.3.0

Python current version: 0.3.0

Node.js current version: 0.3.0

First capture

Private by default

Capture options

Free account

Shotbot Pro

PDF (only with `--format=pdf`)

CLI options

Persistent defaults

Using in CI/CD | GitHub Actions, GitLab CI, Makefile

Environment variables

Exit codes

Other commands

Resources

API documentation

Integration examples

FAQ | CLI category

Screenshots with Claude Code

Download the PHP CLI

Download the Python CLI

Download the Node.js CLI

CLI Tools

Install

Available clients

PHP current version: 0.3.0

Python current version: 0.3.0

Node.js current version: 0.3.0

First capture

Private by default

Capture options

Free account

Shotbot Pro

PDF (only with --format=pdf)

CLI options

Persistent defaults

Using in CI/CD | GitHub Actions, GitLab CI, Makefile

Environment variables

Exit codes

Other commands

Resources

API documentation

Integration examples

FAQ | CLI category

Screenshots with Claude Code

Download the PHP CLI

Download the Python CLI

Download the Node.js CLI

PDF (only with `--format=pdf`)