How to Take Website Screenshots from the Command Line and AI Agents

Quick answer: For one screenshot, run Chrome Headless with --screenshot. For an AI agent that must navigate or interact before capturing, use Playwright CLI. Choose viewport, element, or full-page capture deliberately, and treat timeouts as maximum waits rather than proof that dynamic content is finished.

chrome --headless --screenshot --window-size=412,892 https://developer.chrome.com/

Chrome saves screenshot.png in the current directory. The official Chrome Headless command-line reference documents this command, viewport sizing, timeouts, DOM dumping, and PDF output.

1. Pick the right command-line workflow

Need	Best fit	Why
One rendered page, no interaction	Chrome Headless	Shortest command and explicit viewport control.
Navigate, click, fill forms, then capture	Playwright CLI	Maintains an interactive browser session and page snapshots for agent decisions.
Capture an element or full scrollable page	Playwright CLI	Supports target selectors and `--full-page`.
Repeated production captures without browser setup	ScreenshotNeo	HTTP API, cleanup of consent UI, usage headers, and an MCP server for agents.

2. One-off screenshots with Chrome Headless

Basic capture

chrome --headless --screenshot https://example.com/

The output is screenshot.png in the working directory. Add a controlled viewport when responsive layout matters:

chrome --headless --screenshot --window-size=1440,900 https://example.com/

Wait for loading

chrome --headless --screenshot --timeout=10000 https://example.com/

--timeout is a maximum wait in milliseconds before capture. It does not guarantee that every asynchronous request, animation, lazy image, or client-side render has reached a stable state.

Choose an output type

Chrome’s --print-to-pdf creates a PDF, which is separate from a screenshot:

chrome --headless --print-to-pdf=page.pdf https://example.com/

--dump-dom prints the serialized DOM after scripts run; it does not create an image.

Repeatable shell script

#!/usr/bin/env bash
set -euo pipefail

url="${1:?usage: $0 URL [output.png]}"
output="${2:-screenshot.png}"
width="${WIDTH:-1440}"
height="${HEIGHT:-900}"
timeout_ms="${TIMEOUT_MS:-10000}"

chrome --headless \
  --screenshot="$output" \
  --window-size="${width},${height}" \
  --timeout="$timeout_ms" \
  "$url"

echo "Saved $output"

Run it with WIDTH=1280 HEIGHT=800 TIMEOUT_MS=15000 ./capture.sh https://example.com/ home.png.

3. Interactive screenshots with Playwright CLI

Playwright’s CLI is designed for browser automation and coding agents. It runs headless by default, supports Chromium, Firefox, WebKit, and Microsoft Edge, and exposes snapshots of the current page state so an agent can reason about the next action. See the official Coding agents guide and Screenshots & PDF reference.

Install and open a page

npm install -g playwright
playwright install
playwright-cli open https://example.com
playwright-cli screenshot --filename=example.png

Let an agent inspect and interact

playwright-cli open https://example.com
playwright-cli snapshot
# Use the references shown by the snapshot for actions, then capture:
playwright-cli click e12
playwright-cli snapshot
playwright-cli screenshot --filename=after-click.png

The exact element reference (such as e12) comes from the snapshot for the current page state. Take a new snapshot after navigation or an interaction because references can change.

Select capture scope

# Visible viewport
playwright-cli screenshot --filename=viewport.png

# Full scrollable page
playwright-cli screenshot --full-page --filename=full-page.png

# A specific element (replace the target with the reference or selector supported by your CLI version)
playwright-cli screenshot e12 --filename=element.png

# High-resolution device pixels
playwright-cli screenshot --hires --filename=retina.png

# JPEG or WebP by extension
playwright-cli screenshot --filename=page.jpg
playwright-cli screenshot --filename=page.webp

High-resolution output can improve text legibility. It also means image coordinates are device pixels, while mouse commands use CSS-pixel coordinates; keep that distinction in mind when an agent uses a screenshot to choose where to click.

Choose a browser

playwright-cli open --browser=firefox https://example.com
playwright-cli open --browser=webkit https://example.com
playwright-cli open --browser=msedge https://example.com

Use the browser that matches the rendering you need to inspect. Browser engines can produce different font metrics, media-query results, and layout.

4. A practical AI-agent screenshot loop

Open the target URL.
Take a snapshot so the agent has page structure and element references.
Perform required navigation, consent handling, form filling, or clicks.
Take another snapshot after each meaningful state change.
Select viewport, element, or full-page scope.
Save with a deterministic filename and record the URL, viewport, browser, and timestamp.

playwright-cli open https://example.com/login
playwright-cli snapshot
# Agent identifies the username and password references
playwright-cli fill e4 "user@example.com"
playwright-cli fill e5 "$PASSWORD"
playwright-cli click e8
playwright-cli snapshot
playwright-cli screenshot --full-page --filename=logged-in.png

Keep secrets in environment variables or the agent’s secret store. Do not put credentials in shell history, source files, or screenshot filenames.

5. Viewport, full-page, and element decisions

Viewport: captures what is visible at the current scroll position. Use it for responsive checks and above-the-fold reviews.
Full page: captures the scrollable document. Use it for documentation, audits, and archival images. Very long pages can create large files and may expose sticky headers repeatedly.
Element: captures one component such as a pricing card or chart. It avoids unrelated page content and is usually easier to compare in visual tests.
High resolution: increases device-pixel detail. Balance readability against file size and coordinate conversion for agent actions.

6. Dynamic pages and timing

A fixed timeout is only a ceiling. Pages may continue changing because of API calls, lazy loading, animations, ads, consent dialogs, or client-side hydration. For a stable capture:

Wait for a meaningful selector or state rather than an arbitrary long sleep when your automation tool supports it.
Scroll through long pages before a full-page capture when images load lazily.
Disable or wait for animations if visual consistency matters.
Capture after navigation has completed and after the interaction that reveals the intended state.

Neither the Chrome nor Playwright documentation establishes one universal wait strategy for every site, so the correct condition is page-specific.

7. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns PNG, JPEG, WebP, or PDF, with options for full-page and element capture, dark mode, device presets, retina scale, custom CSS and JavaScript, clicks, waits, blocking, headers, cookies, user agents, timezone, geolocation, transparency, resizing, caching, signed links, asynchronous jobs, bulk capture, and usage reporting. See the ScreenshotNeo documentation.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed. Response headers identify the result with X-Page-Verdict and X-Billed.
An MCP server gives Claude, Cursor, and other MCP clients take_screenshot, get_page_info, and capture_pdf tools.
The Free plan includes 1,000 screenshots per month with no card. Paid plans start at $5 for 3,000 shots; yearly billing gives two months free.

Create a free ScreenshotNeo account and start with 1,000 screenshots a month at no charge.

8. Troubleshooting

Symptom	Likely cause	Fix
Screenshot is blank	Page failed to load, blocked navigation, or capture happened before rendering.	Open the URL interactively, inspect console/network errors, increase the maximum wait, and wait for a page-specific selector.
Lazy images are missing	Images load only after scrolling or intersection events.	Scroll through the page before capture or use a full-page workflow that triggers lazy loading.
Cookie banner covers content	Consent UI is part of the rendered page.	Use Playwright to locate and click the consent control, or use ScreenshotNeo’s consent cleanup.
Wrong responsive layout	Viewport was not specified or differs from the target device.	Set `--window-size` in Chrome or use the relevant Playwright/browser viewport.
Element reference no longer works	Navigation or DOM changes invalidated the snapshot.	Take a fresh snapshot after each state change and use the new reference.
Text looks blurry	Image has too few device pixels for the display or review size.	Use `--hires` in Playwright or a retina scale option in an API.
Full-page image is unexpectedly huge	Long document, large scale, or heavy assets.	Capture a target element, reduce scale, choose WebP/JPEG, or split the page into sections.
PDF was expected but PNG was created	Screenshot and print-to-PDF are different commands.	Use Chrome’s `--print-to-pdf` or an API PDF operation explicitly.

9. Performance, reliability, and cost notes

Use a fixed viewport and deterministic output names for repeatable jobs.
Reuse a Playwright browser session when capturing several states; avoid launching a new browser for every step.
Full-page and high-resolution captures consume more memory and produce larger files than viewport or element captures.
Cache static pages when your workflow permits it, and record the capture configuration beside the image.
Retry only transient navigation failures. Repeating a capture without changing the cause will not fix a bot check, broken URL, or permanently missing selector.
Chrome and Playwright documentation provide commands and options but no universal speed or reliability benchmark; measure your own pages and infrastructure.
With ScreenshotNeo, cache hits and failed or unusable results are not billed, and the response headers expose billing and page verdicts for accounting.

10. Security checklist for agents

Allowlist domains an agent may visit.
Keep API keys, cookies, and credentials outside prompts and command history.
Do not capture pages containing secrets unless storage and access are controlled.
Review scripts that click, submit, or download before running them against production accounts.
Strip sensitive metadata from files before sharing screenshots externally.

11. FAQ

Does Chrome Headless capture the whole page?

The basic --screenshot command captures the configured viewport. Use Playwright’s --full-page option or an API full-page option for the scrollable document.

Can I use an AI agent without Playwright?

Yes. An agent can issue Chrome commands, but Playwright CLI provides a page-state snapshot and interaction loop designed for coding-agent workflows.

What is the difference between a screenshot and a PDF?

A screenshot is a raster image such as PNG, JPEG, or WebP. PDF output is a document format with its own print settings and page layout.

Consent UI is part of the page unless your automation dismisses it. ScreenshotNeo can remove known consent platforms before capture.

Which scope should visual tests use?

Use an element for component tests, a viewport for responsive checks, and full-page only when document-level layout is the subject.