Use DOMShot from shell commands.

When to use the CLI

Use the CLI when your agent can run shell commands. It is the simplest automation surface: command in, PNG files and JSON metadata out. The agent can read the JSON, decide whether the capture is good enough, and retry if needed.

Install

Install the package where commands will run. The second command installs the local Chromium browser used for default captures. If npm cannot find the package yet, the public package release is still pending approval.

npm install @domshot/agent
npx playwright install chromium

Expected result: the domshot and domshot-mcp binaries are available to your project.

Capture one element

Use this when you want one PNG. Pass a selector when you know the exact element. Pass --target when the agent only knows what the element should be.

domshot capture https://example.com "h1" --out artifacts/heading.png
domshot capture https://example.com --target "pricing card" --out artifacts/pricing-card.png
domshot capture https://example.com ".hero" --preset studio --viewport 1440x1000

Expected output: one PNG file and JSON metadata with the chosen selector, dimensions, fallback flag, warnings, and byte count when available.

Style the output

Use styling flags when the screenshot is meant for a homepage, feature section, post, or docs page. Transparent backgrounds are useful when another design will place the image; shadows and padding make standalone captures feel finished.

domshot capture https://example.com --target "pricing card" \
  --out shots/pricing.png \
  --background transparent \
  --shadow soft \
  --padding 56 \
  --aspect-ratio 1:1 \
  --output-width 1200

Expected output: a 1200px-wide square PNG with transparent background, padding, and a soft shadow around the selected element.

Inspect, recommend, and plan

Use these commands when the page is unfamiliar or the agent is creating a larger piece of content. They help the agent understand what the page can offer before writing final images.

domshot inspect https://example.com --intent "homepage feature visuals" --limit 8
domshot recommend https://example.com --intent "homepage feature section" --limit 4
domshot plan https://example.com \
  --intent "homepage feature section" \
  --target "feature cards" \
  --count 4 \
  --out .domshot/plan.json \
  --style auto

Capture sets and shot packs

Use capture-set when you want several similar elements, such as pricing cards. Use shot-pack when you want a polished group of assets for a section, post, docs page, or pricing page.

domshot capture-set https://example.com \
  --target "pricing cards" \
  --out-dir shots/pricing \
  --style auto

domshot shot-pack https://example.com \
  --intent "homepage feature section" \
  --target "feature cards" \
  --count 4 \
  --out-dir shots/homepage \
  --style auto

Expected output: PNG files in the output folder. Shot packs also include a contact sheet and sanitized report explaining what was selected, rejected, and why.

Capture from a saved plan

Use this after the agent has reviewed a plan and decided the shots are worth capturing. The saved plan's selectors and style suggestions become the source of truth.

domshot shot-pack --from-plan .domshot/plan.json \
  --url https://example.com \
  --out-dir artifacts/homepage

domshot capture-set --from-plan .domshot/plan.json \
  --url https://example.com \
  --out-dir artifacts/homepage

Next step: check the generated report and contact sheet. If the page changed since the plan was created, create a fresh plan.

Current-page CDP workflow

Use current-page commands when the browser is already on the right page, such as a logged-in app or a page with manual setup. CDP is Chrome's debugging connection: DOMShot attaches to that browser instead of opening a new blank session.

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
  --remote-debugging-port=9222 \
  --user-data-dir="$PWD/.domshot/chrome-profile"

domshot capture-current --target "balance card" \
  --browser cdp \
  --cdp http://127.0.0.1:9222 \
  --out shots/balance-card.png

domshot shot-pack-current \
  --intent "dashboard visuals" \
  --target "dashboard cards" \
  --browser cdp \
  --cdp http://127.0.0.1:9222 \
  --out-dir shots/dashboard \
  --style auto

Use a dedicated automation profile, not your normal Chrome profile. Keep private screenshots and reports out of commits.

Output

CLI commands print JSON metadata. Capture commands include path, dimensions, selector, fallback status, warnings, and byte counts when available. Shot packs also include contact sheet and report paths.

{
  "path": "/absolute/path/shots/pricing.png",
  "width": 1200,
  "height": 1200,
  "selector": "[data-card='pricing']",
  "fallback": false,
  "warning": null
}