ScreenshotOne CLI

A command line interface to integrate ScreenshotOne (the screenshot API for developers) into your workflows.

ScreenshotOne is one of the best screenshot APIs, it supports:

• rendering (full page, too) screenshots of URLs, including HTML and Markdown;
• rendering PDFs of URLs or from HTML;
• rendering scrolling screenshots of URLs;
• rendering short videos of URLs;
• blocking chat, banners and ads;
• and many more.

Check the ScreenshotOne documentation for more details.

Installation

Using Bun (recommended)

bun install

Using Docker

docker build -t screenshotone-cli .

Configuration

Sign up to get your access key and secret key.

Environment Variables

export SCREENSHOTONE_ACCESS_KEY="your-access-key"
export SCREENSHOTONE_SECRET_KEY="your-secret-key"

Configuration File

Create ~/.screenshotone/config.json:

{
    "access_key": "your-access-key",
    "secret_key": "your-secret-key"
}

CLI Flags

screenshotone take https://example.com --access-key=xxx --secret-key=yyy

If you are using Docker:

docker run -e SCREENSHOTONE_ACCESS_KEY=xxx -e SCREENSHOTONE_SECRET_KEY=yyy \
  screenshotone/cli take https://example.com

Commands

Core Commands

take - Take a screenshot

screenshotone take <url|html|markdown> [options]

# Examples
screenshotone take https://example.com -o screenshot.png
screenshotone take https://example.com --format=jpg --image-quality=90 -o photo.jpg
screenshotone take "<h1>Hello</h1>" --html -o hello.png
screenshotone take "# Hello World" --markdown -o hello.png

animate - Create animated video/gif

screenshotone animate <url> [options]

# Examples
screenshotone animate https://example.com --duration=5 -o video.mp4
screenshotone animate https://example.com --format=gif --duration=3 -o animation.gif

usage - Check API usage

screenshotone usage
screenshotone usage --json

Shortcut Commands

screenshot - Take a PNG screenshot (default)

screenshotone screenshot https://example.com -o shot.png

pdf - Generate PDF

screenshotone pdf https://example.com -o document.pdf
screenshotone pdf https://example.com --pdf-print-background -o styled.pdf

full-page - Full page screenshot

screenshotone full-page https://example.com -o full.png
screenshotone full-page https://example.com --full-page-scroll -o scrolled.png

scrolling - Scrolling video

screenshotone scrolling https://example.com --duration=5 -o scroll.mp4
screenshotone scrolling https://example.com --scroll-duration=3000 --format=gif -o scroll.gif

video - Record video

screenshotone video https://example.com --duration=10 -o recording.mp4

html - Render HTML

screenshotone html "<h1>Hello World</h1><p>This is a test</p>" -o hello.png

markdown - Render Markdown

screenshotone markdown "# Hello World" -o hello.png

Output Options

Option	Description
-o, --output <file>	Save to file
--stdout	Output binary to stdout (for piping)
--json	Output signed URL as JSON

Examples

# Save to file
screenshotone take https://example.com -o screenshot.png

# Pipe to another command
screenshotone take https://example.com --stdout | imgcat

# Get signed URL as JSON
screenshotone take https://example.com --json
# Output: {"url": "https://api.screenshotone.com/take?..."}

All Options

Viewport

Option	Description
--viewport-width	Width in pixels
--viewport-height	Height in pixels
--viewport-device	Device to emulate
--viewport-mobile	Mobile viewport
--viewport-has-touch	Touch support
--viewport-landscape	Landscape orientation
--device-scale-factor	Scale factor (1, 2, or 3)

Format & Quality

Option	Description
--format	png, jpg, webp, gif, pdf, html
--image-quality	Quality 1-100 (jpg, webp)
--image-width	Resize width
--image-height	Resize height
--omit-background	Transparent background

Full Page

Option	Description
--full-page	Capture full page
--full-page-scroll	Scroll before capture
--full-page-scroll-delay	Delay between scrolls
--full-page-max-height	Maximum height
--full-page-algorithm	Algorithm to use
--capture-beyond-viewport	Capture beyond viewport

PDF Options

Option	Description
--pdf-print-background	Include background
--pdf-fit-one-page	Fit to one page

Blocking

Option	Description
--block-ads	Block advertisements
--block-cookie-banners	Block cookie banners
--block-chats	Block chat widgets
--block-trackers	Block trackers
--block-banners-by-heuristics	Block banners
--block-requests	Block URLs (array)
--block-resources	Block resource types

Selectors

Option	Description
--selector	Element to capture
--hide-selectors	Elements to hide
--wait-for-selector	Wait for element
--scroll-into-view	Scroll element into view
--error-on-selector-not-found	Error if not found

Timing

Option	Description
--delay	Delay before capture (ms)
--timeout	Request timeout (ms)
--navigation-timeout	Navigation timeout (ms)
--wait-until	Wait for events

Caching

Option	Description
--cache	Enable caching
--cache-ttl	Cache TTL in seconds
--cache-key	Custom cache key

Storage (S3)

Option	Description
--store	Store to S3
--storage-path	Storage path
--storage-bucket	Bucket name
--storage-access-key-id	AWS access key
--storage-secret-access-key	AWS secret key
--storage-endpoint	Custom endpoint
--storage-class	Storage class
--storage-acl	ACL
--storage-return-location	Return location

Request

Option	Description
--user-agent	Custom user agent
--authorization	Authorization header
--proxy	Proxy URL
--cookies	Cookies (array)
--headers	Headers (array)
--time-zone	Time zone
--ip-country-code	IP country code
--bypass-csp	Bypass CSP

Geolocation

Option	Description
--geolocation-latitude	Latitude
--geolocation-longitude	Longitude
--geolocation-accuracy	Accuracy in meters

Rendering

Option	Description
--dark-mode	Dark mode
--reduced-motion	Reduced motion
--media-type	screen or print
--styles	Custom CSS
--scripts	Custom JavaScript
--request-gpu-rendering	GPU rendering
--ignore-host-errors	Ignore host errors

Clipping

Option	Description
--clip-x	X coordinate
--clip-y	Y coordinate
--clip-width	Width
--clip-height	Height

Metadata

Option	Description
--metadata-image-size	Include image size
--metadata-fonts	Include fonts
--metadata-open-graph	Include Open Graph
--metadata-page-title	Include page title
--metadata-content	Include content
--metadata-http-response-status-code	Include status
--metadata-http-response-headers	Include headers

Async & Webhooks

Option	Description
--async	Async execution
--webhook-url	Webhook URL
--webhook-sign	Sign webhook

Failure

Option	Description
--fail-if-content-contains	Fail on content
--fail-if-gpu-rendering-fails	Fail on GPU error

Vision (OpenAI)

Option	Description
--openai-api-key	OpenAI API key
--vision-prompt	Vision prompt
--vision-max-tokens	Max tokens

Animation Options

Option	Description
--duration	Duration in seconds
--scenario	Animation scenario
--width	Video width
--height	Video height
--aspect-ratio	Aspect ratio

Scrolling Animation

Option	Description
--scroll-delay	Scroll delay
--scroll-duration	Scroll duration
--scroll-start-delay	Start delay
--scroll-start-immediately	Start immediately
--scroll-back	Scroll back
--scroll-back-after-duration	Scroll back after
--scroll-back-algorithm	Scroll back algorithm
--scroll-complete	Complete scroll
--scroll-by	Scroll by pixels
--scroll-easing	Easing function
--scroll-stop-after-duration	Stop after duration
--scroll-try-navigate	Navigate on scroll
--scroll-navigate-after	Navigate after
--scroll-navigate-to-url	Navigate URL
--scroll-navigate-link-hints	Link hints

Docker Usage

# Build the image
docker build -t screenshotone-cli .

# Run with environment variables
docker run -e SCREENSHOTONE_ACCESS_KEY=xxx -e SCREENSHOTONE_SECRET_KEY=yyy \
  screenshotone-cli take https://example.com --stdout > screenshot.png

# Run with mounted volume for output
docker run -v $(pwd)/output:/output \
  -e SCREENSHOTONE_ACCESS_KEY=xxx -e SCREENSHOTONE_SECRET_KEY=yyy \
  screenshotone-cli take https://example.com -o /output/screenshot.png

Development

# Install dependencies
bun install

# Run
bun run index.ts take https://example.com

# Build binary
bun build index.ts --compile --outfile screenshotone

License

ScreenshotOne CLI is licensed under the MIT License.