Command line

shotlist [<name>…] [options]

With one or more names, shotlist takes those recipes. With no names and no options, it lists the recipes it found.

Options

--login

Opens a browser at site.url, waits while you sign in, and writes the session named on the command line. With --using the browser is headless and a macro signs in instead, so the run names the host and the variables the macro may read before it starts.

$ npx shotlist --login admin --using sign-in --allow-env ADMIN_PASSWORD
Signing in at https://app.example.com with `sign-in`, which may type ADMIN_PASSWORD into it.
  ✓ wrote .shotlist/admin.json
    left out 23 cookies and 1 origin for google.com, accounts.google.com, youtube.com

Nothing is written when the sign-in did not take, or when what is left after narrowing no longer satisfies verify. An --untrusted run is refused a session, so --login has no untrusted mode.

Exit codes

Environment variables

These are read from the process environment. shotlist does not load a .env file — that name is one it refuses to open — so anything kept there has to be in the environment before the command runs. See Capture a page behind a sign-in.

Network destinations

A bare host approves HTTPS on port 443. Prefix it with *. to approve its HTTPS subdomains. HTTP, WebSocket and non-default ports use a full destination, such as http://localhost:4321 or wss://events.example.com. Protocols match exactly; HTTP and WebSocket connections use separate approvals. An approved HTTP destination also permits a redirect to HTTPS port 443 on the same host. A TCP readiness probe uses tcp://localhost:4321.

Check statuses

JSON report

Written by --check --json. Human-readable output moves to stderr.

{
  "changed": 1,
  "total": 1,
  "results": [
    {
      "name": "order-row",
      "status": "changed",
      "ratio": 0.0213,
      "shot": "screenshots/out/order-row.png",
      "against": "content/guide/images/order-row.png",
      "diff": "screenshots/out/diff/order-row.png"
    }
  ],
  "failures": [],
  "drift": [{ "field": "chromium", "was": "141.0.0.0", "now": "139.0.0.0" }],
  "operatorDestinations": []
}

Work limits

Baseline file

--install writes shotlist.baseline.json beside the configuration file, recording the shotlist, Playwright and Chromium versions and the platform that produced the images.

Node.js API

openRun() takes explicit Operator authority and opens the configuration and Library. Capture and Checking requests run through that object.

import { lint, openRun, type CheckReport } from 'shotlist'

const authority = { untrusted: false }
const run = openRun(authority, 'shotlist.config.yaml')

await run.capture({ recipes: ['order-row'], install: true })

const controller = new AbortController()
const report: CheckReport = await run.check({
  all: true,
  diff: true,
  keepGoing: true,
  signal: controller.signal,
  onProgress: async (progress) => console.log(progress.type),
})

const review = lint(authority, 'shotlist.config.yaml')

A request selects { recipes: names } or { all: true }. keepGoing, signal and onProgress apply to Capture and Checking; install applies to Capture and diff to Checking. Progress observers are awaited in order. Their failures appear in warnings rather than changing a Recipe result.

Capture installs images only after every selected Recipe and owned resource has finished cleanup. Its report separates Recipe results, resource failures, Installation outcomes and Baseline recording. A Run accepts one request at a time and remains reusable after that request settles.

JSON Schemas

Reference one from a file for editor completion and inline validation:

# yaml-language-server: $schema=../../node_modules/shotlist/dist/recipe.schema.json

The config's schema was dist/schema.json before 0.4.0, which named one of three files "the schema". That file is still written and shotlist/schema.json still resolves to the config schema, so an existing YAML header or editor setting keeps working. Both go at 1.0.