Skip to main content

​
Overview

Capture screenshots of the entire page, viewport, or specific elements. Automatically resizes images to optimize for Claude Vision token costs (~1,600 tokens max) unless disabled.

​
Syntax

bdg dom screenshot <path> [options]

​
Arguments

​
path
string
required
Output file path (PNG/JPEG), or directory for --follow mode

​
Options

​
Capture target

​
--selector
string
CSS selector for element capture
​
--index
number
Cached element index (0-based) from previous query
​
--scroll
string
Scroll element into view before capture

​
Image format

​
--format
string
Image format: png or jpeg (default: png)
​
--quality
number
JPEG quality 0-100 (default: 90)

​
Capture mode

​
--no-full-page
flag
Capture viewport only instead of full page (default: full page)
​
--no-resize
flag
Disable auto-resize, capture at full resolution

​
Continuous capture

​
--follow
flag
Continuous capture mode to directory
​
--interval
number
Capture interval for --follow in milliseconds (default: 1000)
​
--limit
number
Maximum frames for --follow mode

​
Output

​
--json
flag
Output metadata as JSON

​
Auto-resize behavior

By default, screenshots are optimized for Claude Vision API:
  • Images exceeding 1568px on longest edge are scaled down
  • Tall pages (aspect ratio > 3:1) automatically capture viewport only
  • Targets ~1,600 tokens per image
  • Accounts for device pixel ratio (Retina displays)
Disable with --no-resize for full resolution.

​
Examples

​
Full page capture

# Auto-resized for Claude Vision
bdg dom screenshot page.png

# Full resolution
bdg dom screenshot page.png --no-resize

# JPEG format
bdg dom screenshot page.jpg --format jpeg --quality 90

​
Viewport capture

# Visible area only
bdg dom screenshot viewport.png --no-full-page

# Scroll then capture viewport
bdg dom screenshot section.png --scroll "#pricing" --no-full-page

​
Element capture

# By selector
bdg dom screenshot button.png --selector "#submit-btn"

# By cached index
bdg dom query "button"
bdg dom screenshot button.png --index 0

​
Continuous capture

# Capture every second to directory
bdg dom screenshot ./frames --follow
# Creates: 001.png, 002.png, 003.png...

# Custom interval and limit
bdg dom screenshot ./frames --follow --interval 500 --limit 10

# JPEG sequence
bdg dom screenshot ./frames --follow --format jpeg

​
Output metadata

​
Human-readable format

$ bdg dom screenshot page.png
Screenshot saved: /path/to/page.png
Format: png
Dimensions: 1200x3200 (resized from 1920x5120)
Size: 245.3 KB
Mode: full_page
Tokens: ~1,584 (saved ~4,201 tokens via resize)

​
JSON format

{
  "version": "0.5.1",
  "success": true,
  "data": {
    "path": "/path/to/page.png",
    "format": "png",
    "width": 1200,
    "height": 3200,
    "size": 251187,
    "fullPage": true,
    "captureMode": "full_page",
    "finalTokens": 1584,
    "resized": true,
    "originalWidth": 1920,
    "originalHeight": 5120,
    "originalTokens": 5785
  }
}

​
Capture modes

​
Full page (default)

bdg dom screenshot page.png
  • Captures entire scrollable page
  • Auto-resizes if height exceeds optimal size
  • Falls back to viewport for very tall pages (aspect ratio > 3:1)

​
Viewport only

bdg dom screenshot visible.png --no-full-page
  • Captures only visible area
  • Faster than full page
  • Useful for above-the-fold content

​
Element clipping

bdg dom screenshot element.png --selector "#chart"
  • Captures element’s bounding box only
  • Auto-resizes if element is large
  • Element must be visible (not display: none)

​
Scroll + capture

bdg dom screenshot footer.png --scroll "footer" --no-full-page
  • Scrolls element into view
  • Waits for lazy-loaded content
  • Captures viewport after scroll
  • Restores original scroll position

​
Token optimization

​
Why auto-resize?

Claude Vision API charges by image resolution:
  • Images resize to fit within 1568px on longest edge
  • Target: ~1,600 tokens per image (cost-effective sweet spot)
  • Maintains aspect ratio, quality sufficient for UI analysis

​
When to use --no-resize

bdg dom screenshot full-res.png --no-resize
Use full resolution when:
  • Need to read small text or details
  • Creating reference images for humans
  • Image will be downscaled elsewhere
  • Not using with Claude Vision API

​
Token estimates

Token calculation formula: 
tokens = (width / 512) × (height / 512) × 170 + 85
Examples:
  • 1920×1080: ~765 tokens → ~685 tokens (resized to 1568×882)
  • 1920×5120: ~5,785 tokens → ~1,584 tokens (resized to 1200×3200)
  • 1920×8000: Falls back to viewport (~1,600 tokens)

​
Exit codes

​
0
number
Success - screenshot captured
​
81
number
INVALID_ARGUMENTS - invalid quality or dimensions
​
83
number
RESOURCE_NOT_FOUND - element not found
​
87
number
STALE_CACHE - cached index invalid
​
102
number
CDP_TIMEOUT - CDP operation timed out

​
Troubleshooting

​
Element not captured

# Verify element exists
bdg dom query "#element"

# Check element dimensions
bdg dom eval 'document.querySelector("#element").getBoundingClientRect()'

# Scroll into view first
bdg dom scroll "#element"
bdg dom screenshot element.png --selector "#element"

​
Image too small

# Disable auto-resize
bdg dom screenshot full-res.png --no-resize

# Or increase JPEG quality
bdg dom screenshot high-quality.jpg --quality 100

​
Missing lazy-loaded content

# Scroll to trigger loading
bdg dom scroll --bottom
bdg dom screenshot page.png

# Or use --scroll option
bdg dom screenshot page.png --scroll "footer"

Build docs developers (and LLMs) love

Get started for freeTalk to us