shotbot 0.1.0

CLI for the Shotbot screenshot API

shotbot-python-cli

A single-file Python CLI for the Shotbot screenshot API. Same flag names, exit codes, and config-file layout as the PHP and Node.js clients | scripts written for one work as-is with the others.

Documentation: https://www.shotbot.net/screenshot-cli-tools/ (English) / https://www.shotbot.fr/outil-cli-capture-ecran/ (French).

Requirements

• Python 3.8+
• Standard library only | no pip install needed.

Install

curl -fsSL https://api.shotbot.net/cli/python/shotbot -o shotbot \
  && chmod +x shotbot \
  && ./shotbot help

To put it on your $PATH:

sudo mv shotbot /usr/local/bin/

First run

On first use you'll be prompted for your API key. It is saved to ~/.shotbot-python-cli/config.json (chmod 600). Get a key at https://www.shotbot.net/screenshot-api-key/.

$ shotbot capture --url=https://example.com

No Shotbot API key configured.
Get one at https://www.shotbot.net/screenshot-api-key/

API key: abc123def456
✓ Saved to /home/you/.shotbot-python-cli/config.json (chmod 600)

Usage

shotbot capture --url=https://example.com
shotbot capture --url=https://example.com --output                    # cwd, auto-named
shotbot capture --url=https://example.com --output=screenshots/       # into dir, auto-named
shotbot capture --url=https://example.com --output=hero.jpg           # exact path
shotbot capture --url=https://example.com --full-page --dark
shotbot capture --url=https://example.com --json | jq .

Privacy: any capture saved with --output is never published on the CDN. The CLI requests a private capture, the worker writes the file to a non-public directory on the server, the CLI fetches it once from api.shotbot.net, and the server deletes it on read. There is no public URL at any point | useful for sensitive pages (intranet, dashboards, customer data). Captures without --output keep the existing CDN-backed flow.

Capture options

Free tier

Option	Values	Default
--url	http(s) URL (required)
--format	jpg, png, webp, avif, pdf	jpg
--viewport	360..1920 (px)	1280
--output-size	120..1920 (resize the result, px)	viewport
--wait	0..120 (seconds after page load)	5
--ratio	16:9, 4:3, 1:1, 9:16, etc.	16:9
--full-page	flag	off
--nojs	flag (disable JavaScript before navigation)	off
--color-scheme	dark | light (sets prefers-color-scheme)	off
--hidpi	flag (2x DPR)	off

Pro

Option	Values
--dismiss-cookies	accept | reject (auto-handle cookie consent banners)
--scroll	flag (scroll the page before capture; lazy-load trigger)
--block-ads	flag (block ad-network requests)
--crop-height	10..20000 (crops the result, overrides ratio, implies full-page)
--selector	CSS selector (capture only the matched DOM element)
--http-auth-user	string (HTTP Basic Auth user)
--http-auth-pass	string (HTTP Basic Auth password)

PDF (only when --format=pdf)

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

CLI ergonomics

Option	Values	Default
--output	save image to disk; see below	none
--json	print full JSON response, no chrome	off
--timeout	max seconds to wait for the capture	180

--output automatically requests a private capture | the file is not put on static.shotbot.net. See the privacy note above.

--output modes

Form	Saves to
--output	./<host>-<short_token>.<format> (cwd, auto-named)
--output=screenshots/	screenshots/<host>-<short_token>.<format> (auto-named)
--output=path/to/file.jpg	exactly that path

Auto filename example for https://www.example.com/: example.com-a1b2c3d4.jpg (www. stripped, first 8 chars of the job id, format extension).

Persistent defaults

Save options once and they apply to every capture. Per-call flags always win.

shotbot set full-page                # always full-page
shotbot set output ./shots/          # always save into ./shots/ (and private)
shotbot set viewport 1440            # always render at 1440 px
shotbot set format webp              # always webp

shotbot defaults                     # show what's stored
shotbot defaults --keys              # list every settable key + type
shotbot unset full-page              # forget that default

Booleans accept true/false/yes/no/1/0; bare set <key> on a boolean is shorthand for set <key> true. Defaults live in the same config.json as the API key, under a defaults object.

Free tier

Settable key	Type	Notes
format	string (enum)	jpg / png / webp / avif / pdf
viewport	int	360..1920
output-size	int	120..1920 (resize the result)
wait	int	0..120
ratio	string	16:9, 4:3, 1:1, etc.
color-scheme	string (enum)	dark | light
full-page	bool
nojs	bool	disable JavaScript
hidpi	bool

Pro

Settable key	Type	Notes
dismiss-cookies	string (enum)	accept | reject
scroll	bool	scroll before capture
block-ads	bool
crop-height	int	10..20000
selector	string	CSS selector
http-auth-user	string	HTTP Basic user
http-auth-pass	string	HTTP Basic password

PDF (only when format=pdf)

Settable key	Type	Notes
pdf-page-size	string (enum)	A4/A3/A5/Letter/Legal/Tabloid
pdf-margin	int	0..50 (mm)
pdf-scale	float	0.10..2.00
pdf-landscape	bool

CLI

Settable key	Type	Notes
output	string	path or true; makes every capture private + saved locally
timeout	int	max polling seconds

Other commands

Command	What
shotbot status	Show account plan, credits, quota, captures in flight.
shotbot set <key> [value]	Persist a default option.
shotbot unset <key>	Clear a persisted default.
shotbot defaults [--keys]	List your defaults; --keys lists settable keys.
shotbot config	Print the path to the config file.
shotbot reset	Re-prompt for the API key.
shotbot version	Print the version.
shotbot help	Show help.

Environment

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

Exit codes

Code	Meaning
0	Success.
2	Bad invocation (missing args, bad config, etc.).
3	Network error.
4	API returned an error response.
5	Waitlisted (quota exhausted).
6	Capture failed on the server side.
7	Polling timeout.

CI example

export SHOTBOT_API_KEY=abc123def456
shotbot capture --url=https://staging.example.com --output=before.jpg

License

MIT. See LICENSE.