Screenshot Testing in CI/CD with the SnapSharp CLI

Visual regression testing usually means setting up Playwright, Chromium, and a comparison tool. Or you can take a screenshot with one command and move on with your life.

The SnapSharp CLI captures screenshots from any terminal — including CI/CD pipelines. No browser installation, no Docker configuration, no flaky tests from Chrome version mismatches.

Install

npm install -g snapsharp-cli
# or use without installing:
npx snapsharp-cli <command>

Basic usage

# Set your API key
export SNAPSHARP_API_KEY=sk_live_your_key

# Take a screenshot
snapsharp screenshot https://staging.example.com -o staging.png

# Full-page, dark mode, WebP
snapsharp screenshot https://staging.example.com \
  --full-page --dark-mode -f webp -o staging.webp

# Mobile view
snapsharp screenshot https://staging.example.com \
  --device "iPhone 14" -o mobile.png

CI mode

The ci command exits with code 0 on success and 1 on failure — perfect for pipelines:

snapsharp ci --url https://staging.example.com --output screenshot.png

GitHub Actions example

name: Visual check
on: [pull_request]

jobs:
  screenshot:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Capture staging screenshot
        env:
          SNAPSHARP_API_KEY: ${{ secrets.SNAPSHARP_API_KEY }}
        run: |
          npx snapsharp-cli ci --url https://staging.example.com --output staging.png
          npx snapsharp-cli screenshot https://staging.example.com --device "iPhone 14" -o mobile.png

      - uses: actions/upload-artifact@v4
        with:
          name: screenshots
          path: "*.png"

GitLab CI example

screenshot:
  image: node:20
  script:
    - npx snapsharp-cli ci --url https://staging.example.com --output screenshot.png
  artifacts:
    paths:
      - screenshot.png
  variables:
    SNAPSHARP_API_KEY: $SNAPSHARP_API_KEY

Multiple pages in one pipeline

#!/bin/bash
PAGES=(
  "https://staging.example.com"
  "https://staging.example.com/pricing"
  "https://staging.example.com/dashboard"
  "https://staging.example.com/login"
)

for page in "${PAGES[@]}"; do
  name=$(echo "$page" | sed 's|https://||;s|/|-|g')
  snapsharp screenshot "$page" -o "${name}.png" --block-ads
done

Check usage from the terminal

snapsharp usage
# ━━━━━━━━━━━━━━━━━━━━ 51.4% (12,847 / 25,000)
# Plan: growth | Resets: April 9, 2026

Other commands

# Generate OG image
snapsharp og blog-post --data '{"title":"My Post","author":"Jane"}' -o og.png

# Render HTML file to image
snapsharp html ./email-template.html --width 600 -o email.png

# List available templates
snapsharp templates --json

API key setup

The CLI resolves your key in order:

--key <key> flag
SNAPSHARP_API_KEY environment variable
.snapsharprc file (current directory or home directory)

For CI, use environment variables. For local development, create a .snapsharprc:

echo "sk_live_your_key" > ~/.snapsharprc

Full CLI documentation: snapsharp.dev/docs/cli

Use snapsharp ci to capture and pair it with the /v1/diff endpoint to compare against a stored baseline. Set --fail-threshold to the acceptable diff percentage (e.g. 0.5%). See visual diff docs for the full comparison workflow — perfect for pull request checks.

Can I run the CLI offline or behind a corporate proxy?

The CLI always calls the SnapSharp API — it's not a local renderer. For corporate proxies, the CLI respects standard HTTP_PROXY / HTTPS_PROXY environment variables. Firewalled environments need to whitelist api.snapsharp.dev outbound on port 443.

Does the CLI work with monorepos / multiple apps in one repo?

Yes. Call the CLI in whichever job/directory needs screenshots. Each invocation is independent — no shared state. For monorepos, it's common to screenshot each app's staging URL in its matching CI job.

What exit codes does `snapsharp ci` return?

0 on success (screenshot captured, 200 response). 1 on any failure (auth error, rate limit, network, non-200 from the page). This makes it drop-in compatible with shell && chaining and CI failure handlers.

Can I use the CLI without installing Node.js on CI runners?

Easiest option is npx snapsharp-cli on a node:20 image (shown in the GitLab example above). For non-Node environments, call the REST API directly with curl — see the screenshot endpoint docs for the exact shape.

How do I rotate the API key used in CI?

Create a new key in the dashboard, update the CI secret (e.g. SNAPSHARP_API_KEY in GitHub Actions secrets), then revoke the old key. The CLI picks up the new key on the next run — no code changes needed. For zero-downtime rotation, run both keys in parallel for one deploy cycle.

Related: CLI docs · Pricing · Automate Screenshots with Python