CLI

npx shotlist --init               # write a starter config and recipe
npx shotlist                      # list every recipe
npx shotlist <name> [<name>…]     # shoot into paths.out
npx shotlist <name> --install     # …and copy to its install destination
npx shotlist --all --install      # shoot everything
npx shotlist --all --keep-going   # …carrying on past a recipe that fails
npx shotlist --check              # compare against committed images
npx shotlist --check <name>       # …just these ones
npx shotlist --check --diff       # …and write a before/after/changed image
npx shotlist --check --json       # …and report it as JSON on stdout
npx shotlist --config <file>      # use a specific config
npx shotlist --help               # the same list, from the tool
npx shotlist --version            # print the version

It exits non-zero when anything failed, and names the recipe and the key inside it that could not be resolved — recipe "order-row": marks.amount — no element matched.

For a config that is not yours, and what an operator grants it — see what a config can do.

npx shotlist --check --untrusted        # the config is not yours
npx shotlist --allow docs.example.com  # …and this host too; repeatable
npx shotlist --allow-path /srv/shared  # …and this directory too; repeatable
npx shotlist --deny fixtures           # never touch this name; repeatable

Using it from code

The command line is a thin wrapper. Everything it does is available directly.

import { check, loadConfig, loadLibrary, shoot, withNumbering } from 'shotlist'

const loaded = loadConfig()
const { paths, finders } = loaded.config
const library = loadLibrary({ ...paths, finders })

const recipe = withNumbering(library.recipes.get('order-row')!)
await shoot(recipe, library, loaded, { install: true })

const results = await check([recipe], library, loaded)

Pass a browser to shoot to reuse one across many recipes; without it each call launches and closes its own.

Editor support

The JSON Schemas ship with the package, generated from the same definitions that validate at run time. Point at them for autocomplete and inline validation.

screenshots/recipes/order-row.yaml

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

dist/schema.json is the config, dist/macro.schema.json is a macro.

Agent support

A skill for coding agents ships with the package. It covers what reference cannot: how to choose a query that survives a redesign, which side of a mark a label belongs on, and what each error means. Copy it into a project and an agent will pick it up.

mkdir -p .claude/skills
cp -R node_modules/shotlist/skills/shotlist .claude/skills/

It is Markdown with YAML frontmatter and nothing else, so any agent that reads instruction files can use it — point yours at node_modules/shotlist/skills/shotlist/SKILL.md.