AgentScreenshots CLI: Local Visual Checks for Coding Agents

AgentScreenshots is primarily a CLI product.

You install an npm package named agentscreenshots. It exposes the agentshot command. Coding agents can call that command from the same shell they use to edit code, run tests, start dev servers, and inspect files.

npm install -g agentscreenshots
agentshot instructions
agentshot doctor
agentshot status

That small surface is intentional. A coding agent does not need a large browser-control framework every time it changes a button, adjusts a card grid, or fixes responsive spacing. It needs a reliable way to see the rendered result.

The basic command shape

The core command takes a URL and an output path:

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

AgentScreenshots loads the requested page, captures the requested view, and writes the screenshot to disk.

The URL can be anything reachable from the environment where the command runs:

• localhost dev servers
• preview deployments
• staging URLs
• production URLs
• internal pages reachable through local network or VPN

The output is a local PNG or JPEG at the path you provide.

Why local-first matters

Most frontend work by coding agents happens before a page is public.

The app may be running on http://127.0.0.1:5173. It may require local environment variables. It may point at a staging backend. It may be a client project that should not be uploaded to a third-party screenshot service.

With AgentScreenshots, capture stays local to the development workflow. That has practical consequences:

Concern	Local-first CLI behavior
Localhost	Captures directly, no tunnel required
Private previews	Works if the machine can reach the URL
Screenshot files	Saved locally at the requested path
Rendering	Uses the CLI capture engine
Privacy	MVP does not upload screenshots
Metering	Reports successful visual-check usage, not image contents

AgentScreenshots still has backend services for license validation, usage reporting, Stripe billing, dashboard flows, and feedback. Those services do not render screenshots for the MVP.

Useful capture shapes

Good visual checks are usually scoped. A full-page screenshot can be helpful, but agents often need to inspect one section, one viewport, or one UI state.

Full page with lazy content

agentshot "http://localhost:5173" ".agents/screenshots/home-full.png" 
  --scroll 
  --wait 1000 
  --wait-until load

Mobile viewport

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

Specific section

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

Vertical slice

agentshot "http://localhost:5173" ".agents/screenshots/middle.png" 
  --from 1200 
  --to 2200

UI state before capture

agentshot "http://localhost:5173" ".agents/screenshots/menu-hover.png" 
  --hover ".nav-item" 
  --selector "header" 
  --padding 16

agentshot "http://localhost:5173" ".agents/screenshots/cookies-dismissed.png" 
  --click-if-present "#reject-cookies" 
  --height 900 
  --wait 500

App readiness

agentshot "http://localhost:5173/dashboard" ".agents/screenshots/dashboard.png" 
  --wait-for "[data-ready='true']" 
  --wait 500

These commands are readable in a transcript, easy to repeat, and easy to adapt after a failed visual check.

Why shell is a good agent interface

Coding agents already use the shell as a coordination layer.

They run commands like:

npm run check
npm run build
rg "Pricing"
sed -n '1,120p' src/routes/+page.svelte

Putting screenshots behind a shell command means the visual check sits beside the rest of the development workflow:

npm run dev
agentshot "http://127.0.0.1:5173" ".agents/screenshots/home-after.png" --viewport 1440x1000
npm run check

The command is also easy to document in repo instructions:

After meaningful frontend changes, run:

agentshot "<local-or-preview-url>" ".agents/screenshots/<task>/<name>.png" --scroll --wait 1000

Inspect the saved image before saying the UI is done.

That instruction is small enough to survive across projects, agent tools, and conversation compaction.

What the CLI is not

The CLI does not make AgentScreenshots a general browser-control product.

It is not:

• a hosted screenshot API
• a scraping platform
• a browser cloud
• a visual regression suite
• an MCP server
• a replacement for Playwright test suites
• a full end-to-end testing framework

It uses browser automation internally, but the product surface is deliberately narrower: capture a rendered view so an agent can inspect it.

How metering works

The usage unit is a visual check: one successful screenshot through the CLI. Failed captures do not count.

The public plan shape is:

Plan	Included visual checks
Anonymous local trial	50 one-time screenshots
Free	100/month
Solo	2,000/month for EUR 5/month or EUR 50/year
Pro	10,000/month for EUR 20/month or EUR 200/year
Studio	100,000/month for EUR 100/month or EUR 1,000/year

The CLI may contact the backend for license validation and usage reporting. The MVP does not upload screenshot images as part of normal capture.

The practical habit

AgentScreenshots is most useful when it becomes a habit:

1. Change the UI.
2. Capture the affected page, section, or viewport.
3. Inspect the saved image.
4. Fix what the image reveals.
5. Capture again when needed.

That is the whole positioning. The CLI is not a landing page feature checklist. It is a small way to make AI coding agents stop finishing visual work blind.