Introducing the Snapshot Site CLI

We built the Snapshot Site API and SDKs so developers could capture, analyze, and compare pages from inside their own applications. But a lot of the work that touches screenshots and visual diffs does not happen inside an application at all. It happens in a terminal, in a deploy script, or in a CI job that runs on every pull request.

That is the gap the new @snapshot-site/cli fills. It wraps the same screenshot, analyze, and compare operations you already know from the API and SDKs, but exposes them as plain shell commands. No project setup, no client library to import, no boilerplate to write just to check what a page looks like right now.

Why a CLI, Alongside the API and SDKs

The HTTP API and SDKs are the right choice when screenshot, analysis, or comparison logic needs to live inside your product. The CLI is for everything around that:

• Fast local iteration. You want to see what a page looks like, or how it changed, without opening an editor or writing a script.
• CI and shell pipelines. A pipeline step that runs a shell command is simpler to reason about and debug than one that spins up a runtime just to call an SDK.
• One-off comparisons. Checking whether a staging deploy matches production visually is a two-minute task, not a reason to write and maintain code.
• Saving assets locally. Screenshots and diff images come back as files you can drop straight into a build artifact, a report, or a commit.

Installing the CLI

The CLI is distributed as an npm package and installed globally:

pnpm add -g @snapshot-site/cli

Once installed, the snapshot-site command is available anywhere in your shell.

Authenticating

Every command needs an API key, which you create in the Snapshot Site Console. There are two ways to provide it.

The quickest for CI is an environment variable:

export SNAPSHOT_SITE_API_KEY=your_key

For local use, you can log in once and let the CLI persist the key so you do not have to export it in every new shell session:

snapshot-site login --api-key ss_live_xxx
snapshot-site whoami-config
snapshot-site logout

whoami-config confirms which key and configuration the CLI is currently using, which is worth checking before you run anything in a shared or scripted environment. logout clears the stored key when you are done.

The Three Core Commands

Once authenticated, the CLI mirrors the three operations at the heart of Snapshot Site.

Screenshot captures a page as an image:

snapshot-site screenshot --url https://snapshot-site.com --full-size

--full-size captures the entire scrollable page rather than just the visible viewport, which is usually what you want when reviewing a full layout rather than a single fold.

Analyze runs AI analysis over a page:

snapshot-site analyze --url https://snapshot-site.com --enable-summary --enable-quality

--enable-summary returns a written summary of the page, and --enable-quality adds a quality assessment. Both are useful for quickly sanity-checking a page without reading through it manually.

Compare runs a visual diff between two URLs:

snapshot-site compare --before-url https://snapshot-site.com --after-url https://staging.snapshot-site.com --full-size

This is the command that gets the most use in practice: point it at a production URL and a staging or preview URL, and it tells you what actually changed visually, not just what changed in the code.

Using It in CI

The most valuable place to run snapshot-site compare is not on your laptop, it is on every pull request, before anything merges. The idea is straightforward: on each PR, run a comparison between the current production page and the PR's preview deployment, and surface the result as part of the build.

Conceptually, a GitHub Actions step for this looks like:

- name: Install Snapshot Site CLI
  run: pnpm add -g @snapshot-site/cli

- name: Visual diff against production
  env:
    SNAPSHOT_SITE_API_KEY: ${{ secrets.SNAPSHOT_SITE_API_KEY }}
  run: |
    snapshot-site compare \
      --before-url https://snapshot-site.com \
      --after-url https://pr-preview.snapshot-site.com \
      --full-size

The API key lives in your repository secrets, never in the workflow file itself. Because the CLI is a single global install with no project dependencies, this step adds almost no time to a pipeline, and it gives reviewers a visual diff to look at alongside the code diff, before anything ships.

Whether you are checking a single page from your terminal or wiring visual regression checks into every pull request, the goal is the same: catch what changed before it reaches production. Snapshot Site is built to make that check as fast as running one command.