AgentScreenshots CLI

agentshot is a local-first screenshot CLI for AI coding agents. It runs Playwright on your machine, captures a rendered web page, writes a PNG/JPEG to disk, and reports one successful visual check to AgentScreenshots when a license key is configured. A fresh install includes a one-time anonymous allocation of 50 screenshots before signup or auth.

npm install -g agentscreenshots
agentshot auth ags_live_xxx
agentshot "http://127.0.0.1:5173" ".agents/screenshots/home.png" --scroll --wait 1000

Install

Requirements:

• Node.js 20+
• macOS, Linux, or Windows/WSL
• A reachable URL to capture, including localhost URLs

Install globally:

npm install -g agentscreenshots

The package installs the agentshot binary and checks for an existing local Chrome/Chromium browser during postinstall.

• If a local browser is found, AgentScreenshots uses it and skips the Playwright Chromium download.
• If no local browser is found, AgentScreenshots downloads Playwright Chromium automatically.

If browser installation is blocked in your environment, install the package with the automatic browser step disabled:

AGENTSHOT_SKIP_BROWSER_INSTALL=1 npm install -g agentscreenshots
agentshot install-browser

Run agentshot install-browser --force if you want to download Playwright Chromium even when a system browser is already available.

Authenticate

You can start without auth for the first 50 anonymous screenshots. After that, create a free or paid license in the AgentScreenshots dashboard, then save it locally:

agentshot auth ags_live_xxx
agentshot status

The config file is stored at:

~/.config/agentshot/config.json

You can override config for CI or one-off runs:

AGENTSHOT_API_URL
AGENTSHOT_LICENSE_KEY
AGENTSHOT_CONFIG

Capture

Basic full-page capture:

agentshot "http://127.0.0.1:5173" ".agents/screenshots/home.png"

Fast development capture in the OS temp directory:

agentshot "http://127.0.0.1:5173" "home.png" --temp

Lazy-loaded page:

agentshot "http://127.0.0.1:5173" ".agents/screenshots/home.png" --scroll --wait 1000

Fixed top slice:

agentshot "http://127.0.0.1:5173" ".agents/screenshots/hero.png" --height 1200

Vertical slice:

agentshot "http://127.0.0.1:5173" ".agents/screenshots/slice.png" --from 1600 --to 2400

Specific section or component:

agentshot "http://127.0.0.1:5173" ".agents/screenshots/pricing.png" \
  --selector "section:has-text('Pricing')" --padding 24

Mobile viewport:

agentshot "http://127.0.0.1:5173" ".agents/screenshots/mobile.png" \
  --viewport 390x844 --scroll --wait 1000

Dismiss a cookie banner or simple overlay before capture:

agentshot "https://example.com" ".agents/screenshots/home.png" \
  --click-if-present "button:has-text('Reject all')" --wait 500

Reveal hover UI before capture:

agentshot "http://127.0.0.1:5173" ".agents/screenshots/menu-hover.png" \
  --hover ".nav-item" --selector ".nav-region" --padding 24

Commands

agentshot URL OUTPUT [options]
agentshot URL --temp [options]
agentshot URL NAME --temp [options]
agentshot auth LICENSE_KEY [--api-url URL]
agentshot status
agentshot doctor
agentshot install-browser
agentshot instructions
agentshot feedback "MESSAGE" [--kind feedback|bug|idea]
agentshot logout
agentshot help

Important capture flags:

• --scroll: scroll before capture to trigger lazy-loaded content.
• --wait MS: wait after navigation/scroll before capture.
• --selector SELECTOR: capture a Playwright/CSS selector.
• --section SELECTOR: alias for --selector.
• --nth INDEX: capture another selector match.
• --padding PX: add padding around selector captures.
• --height PX: capture from --from or page top to a fixed height.
• --from PX --to PX: capture a vertical page slice.
• --viewport WIDTHxHEIGHT: set viewport size.
• --device-scale-factor N: capture higher-density pixels without changing CSS layout. Defaults to 2; use 1 for smaller files.
• --wait-for CSS: wait for an element before capture.
• --click SELECTOR: click a required Playwright/CSS selector before capture. Searches the main page and child frames. Repeatable.
• --click-if-present SELECTOR: click a Playwright/CSS selector before capture if it appears. Searches the main page and child frames. Repeatable.
• --hover SELECTOR: hover a required Playwright/CSS selector before capture. Searches the main page and child frames. Repeatable.
• --hover-if-present SELECTOR: hover a Playwright/CSS selector before capture if it appears. Searches the main page and child frames. Repeatable.
• --wait-until STATE: load, domcontentloaded, or networkidle.
• --temp: save in the OS temp directory. With a filename hint, for example pricing.png --temp, the output is named like pricing-temp-df2d.png; without a filename hint, the name is derived from the URL. It does not add timed deletion or cleanup tracking.
• --json: print machine-readable output.
• --no-report: skip usage reporting.

Selectors are Playwright locators, so plain CSS, text=Pricing, section:has-text('Pricing'), and xpath=... work.

For live production websites, prefer --wait-until load --wait 1500 over --wait-until networkidle unless you know the page settles cleanly. Analytics, chat widgets, and background requests can keep networkidle from completing.

Screenshots default to --device-scale-factor 2 for sharper image understanding. Use --device-scale-factor 1 for large batch or matrix runs, such as dozens or hundreds of screenshots, when reducing disk/CI artifact size or upload time matters more than visual fidelity. Browser/page zoom is not currently a first-class CLI option; use --viewport for responsive width checks.

For cookie banners and other one-click overlays, use --click-if-present before capture. Prefer reject or close actions when available:

agentshot "https://example.com" ".agents/screenshots/page.png" \
  --click-if-present "button:has-text('Reject all')" \
  --click-if-present "button[aria-label='Close']"

Use --click or --click-if-present for click-driven UI such as modals, drawers, accordions, tabs, dropdown menus, and collapsed content. Use --hover or --hover-if-present for hover-driven UI such as tooltips, hover cards, menu flyouts, hover-revealed controls, and CSS :hover states.

Agent Workflow

Tell your coding agent:

1. Save project captures to .agents/screenshots/, unless the user provides another path or asks for --temp.
2. Use agentshot after meaningful UI changes.
3. Prefer selector or slice captures over huge full-page captures when possible.
4. Open and inspect the saved PNG before judging the UI.

Output path best practices:

• For project captures, pass an explicit output path so the capture lands exactly where the user or agent expects.
• For project work, save screenshots inside the active repo, preferably under .agents/screenshots/.
• Use task-specific subfolders for larger runs, such as .agents/screenshots/qc/, .agents/screenshots/mobile/, or .agents/screenshots/2026-05-17-pricing/.
• Use descriptive filenames that include the page, viewport, section, or state, for example pricing-mobile.png, hero-hover-menu.png, or checkout-modal-closed.png.
• Add .agents/screenshots/ to .gitignore unless the screenshots are intentionally part of the repo.
• For fast development captures that do not need versioned screenshot history, use --temp when available.
• If the user provides a specific output path or saving instructions, use that path and those instructions exactly.

The package includes AGENT-INSTRUCTIONS.md, a copy-paste prompt for Claude Code, Codex, Cursor, Windsurf, and OpenCode.

Playground

The npm package ships offline playground pages under playground/.

PLAYGROUND_DIR="$(npm root -g)/agentscreenshots/playground"
python -m http.server 5197 --bind 127.0.0.1 --directory "$PLAYGROUND_DIR"
agentshot "http://127.0.0.1:5197/" ".agents/screenshots/playground.png" --scroll

Use https://agentscreenshots.com/blog/install for the full live and offline exercise suite.

Usage Reporting

Successful screenshots report one visual check when a license key is configured. Failed captures do not count. Anonymous trial usage is tracked locally. If the backend is temporarily unreachable, the event is queued at:

~/.config/agentshot/usage-queue.jsonl

Queued events sync on the next successful online capture.

Development

npm install
npm run check
npm run build
npm link
agentshot --version

Package smoke test:

npm pack --dry-run