CLI

Capture screenshots, render HTML, generate PDFs, and inspect page metadata from the command line with the ScreenshotAPI CLI.

The ScreenshotAPI CLI is the fastest way to use ScreenshotAPI from local scripts, CI jobs, and AI coding agents. It saves screenshots and PDFs as files by default, prints compact metadata, and does not require Chromium, Playwright, or Puppeteer.

Installation

npm install -g @screenshotapi/cli

Authenticate once:

screenshotapi auth login --key sk_live_your_key_here

For CI and agent environments, prefer an environment variable:

export SCREENSHOTAPI_KEY=sk_live_your_key_here

Never commit API keys. Store SCREENSHOTAPI_KEY in your CI secret manager or local shell environment.

Quick Start

# Capture a URL as PNG
screenshotapi capture https://example.com --out screenshot.png

# Full-page Retina screenshot with cleanup
screenshotapi capture https://example.com \
  --full-page \
  --device-pixel-ratio 2 \
  --block-ads \
  --remove-cookie-banners \
  --out homepage.png

# Render HTML to an image
screenshotapi html --html-file ./page.html --out page.png

# Generate a PDF
screenshotapi pdf https://example.com --out page.pdf

# Fetch page metadata without spending screenshot credits
screenshotapi metadata https://example.com --output json

Agent Skill

Install the bundled agent skill so your AI assistant knows the current command surface and best practices:

npx skills add miketromba/screenshot-saas --skill screenshotapi

The skill delegates to:

screenshotapi learn

That keeps agent instructions tied to the installed CLI version.

Output Modes

Flag	Output	Best for
`--output compact`	One `key=value` line	AI agents and logs
`--output pretty`	Human-readable labels	Interactive terminals
`--output json`	Minified JSON	Scripts and tests
`--output path`	Saved file path only	Shell pipelines

Non-interactive runs default to compact output:

capture path=homepage.png url=https://example.com type=png bytes=184203 contentType=image/png screenshotId=scr_abc durationMs=1934 cache=MISS usageSource=plan creditsRemaining=199

Common Options

Flag	Description
`--out <path>`	Save to a deterministic path.
`--type <png\|jpeg\|webp\|pdf>`	Output type for `capture` and `html`.
`--width <px>` / `--height <px>`	Viewport size.
`--full-page`	Capture the full scrollable page.
`--quality <1-100>`	JPEG/WebP quality.
`--wait-until <event>`	`load`, `domcontentloaded`, `networkidle0`, or `networkidle2`.
`--wait-for-selector <css>`	Wait for a selector before capture.
`--delay <ms>`	Extra wait after load.
`--block-ads`	Block common ad network requests.
`--remove-cookie-banners`	Remove common cookie banners.
`--remove-popups`	Remove common modal overlays.
`--remove-elements <css,...>`	Remove specific selectors.
`--css-file <path>` / `--js-file <path>`	Inject CSS or JavaScript from files.
`--cache-ttl <seconds>`	`0` disables cache; positive values cache identical captures for up to 7 days.

CI Example

- name: Capture production homepage
  env:
    SCREENSHOTAPI_KEY: ${{ secrets.SCREENSHOTAPI_KEY }}
  run: |
    npx @screenshotapi/cli capture https://example.com \
      --full-page \
      --out artifacts/homepage.png \
      --output json