# Configuration file

One `shotlist.config.yaml` in the project root, or a file named with `--config`. Every path in it resolves from the file's own folder.

A key the schema does not know is refused rather than ignored. Before 0.4.0 `site.viewpoint: 3` did nothing at all, which looks exactly like a setting that has no effect.

## site

| Key | Default | Effect |
| --- | --- | --- |
| `url` | required | Where the site is running |
| `serve` | — | Command that starts the site when nothing answers at `url` |
| `allow` | `[]` | Extra network destinations the project approves |
| `viewport` | `1280 × 800` | Browser size |
| `scale` | `2` | Device pixel ratio |
| `theme` | `light` | `light`, `dark` or `no-preference` |
| `reducedMotion` | `true` | Disable animation before capture |
| `ready` | — | Selector awaited after each navigation |
| `settle` | `0` | Extra milliseconds to wait after `ready` |
| `timeout` | `15000` | Milliseconds a step or query may take |
| `sessions` | `{}` | Signed-in browser states by name |

### site.allow

shotlist.config.yaml

```
site:
  allow:
    - assets.example.com
    - '*.payments.example.com'
    - http://localhost:4400
    - wss://events.example.com
```

A bare host means HTTPS port 443. `*.example.com` means its HTTPS subdomains but not `example.com` itself. HTTP, WebSocket and non-default ports use a full destination. Each approval matches its protocol, host and port. HTTP and WebSocket connections use separate entries. An `--untrusted` Run ignores this list and `site.url`.

### site.serve

A string is the command. A mapping accepts:

| Key | Default | Effect |
| --- | --- | --- |
| `command` | required | The program and its arguments; run without a shell |
| `ready` | `site.url` | A URL, a port, or `{ log: <pattern> }` |
| `cwd` | the config file's folder | Where to run the command |
| `env` | `{}` | Environment added to the run's |
| `timeout` | `30000` | Milliseconds to wait for it to answer |

### site.sessions

A bare path, or a mapping. Files are written by `--login` and are never edited by hand.

shotlist.config.yaml

```
site:
  sessions:
    admin: .shotlist/admin.json
    reader:
      path: .shotlist/reader.json
      verify: '[data-signed-in]'
      keep: [accounts.google.com]
```

| Key | Default | Effect |
| --- | --- | --- |
| `path` | required | Where the session file is written and read |
| `verify` | — | Selector present only on a signed-in page |
| `keep` | `[]` | Hosts whose cookies the file keeps besides this site's own |

A session file holds the cookies and local storage for the host in `site.url`. `keep` adds credential hosts; it does not approve a network destination. See [what a session file holds](/docs/explanation/security-model/#sessions). An `--untrusted` Run loads no session.

## paths

| Key | Default | Contains |
| --- | --- | --- |
| `recipes` | `screenshots/recipes` | Recipe files |
| `macros` | `screenshots/macros` | Macro files |
| `data` | `screenshots/data` | Data files |
| `out` | `screenshots/out` | Images written by a run |

## image

| Key | Default | Effect |
| --- | --- | --- |
| `format` | `png` | `png`, `jpeg` or `webp` |
| `quality` | `90` | `1`–`100`, for the lossy formats |

Files are named for the format: `.png`, `.webp`, and `.jpg` for `jpeg`. AVIF is not available. A recipe may override both keys.

## install

A mapping of names to folders. A recipe names one of these under its own `install` key, and `--install` copies the image there.

## finders

Named query templates, called from a recipe by name. `$1` and `$2` stand for the arguments.

shotlist.config.yaml

```
finders:
  listRow:
    css: 'li, div'
    contains: $1
    matching: '\$\d'
    maxChildren: 12
    pick: smallest
```

## allowEnv

A list of variable names a recipe may read as `${env.NAME}`, so a project that always signs in the same way does not repeat `--allow-env` on every run. Names only — the values stay in the environment and never enter the configuration.

shotlist.config.yaml

```
allowEnv:
  - ADMIN_PASSWORD
  - READER_PASSWORD
```

It adds to `--allow-env` and `SHOTLIST_ENV` rather than replacing them, and `SHOTLIST_ENV_DENY` is subtracted from the result. An `--untrusted` run ignores it exactly as it ignores `site.allow`: a configuration nobody vouched for does not choose what it may read.

## deny

File or folder names this project will not read, write or open. Each entry matches one segment of a path, and `*` stands for any run of characters. Checked against filesystem paths and URL paths.

shotlist.config.yaml

```
deny:
  - fixtures
  - '*.sqlite'
```

## check

| Key | Default | Effect |
| --- | --- | --- |
| `threshold` | `0.002` | Fraction of pixels that may differ |
| `tolerance` | `8` | How far one channel may move, out of 255 |

## style

Every drawing constant, with its default. Sizes are in image pixels and do not change with `scale`. A recipe may override any of these under its own `style` key.

shotlist.config.yaml

```
style:
  color: '#DC2626'
  canvas: '#FFFFFF'
  box: { width: 6, radius: 10, pad: 8 }
  arrow: { shaft: 6, headHalf: 19, headLength: 38 }
  label:
    font: 'Arial, Helvetica, sans-serif'
    weight: 700
    size: 44
    fill: '#FFFFFF'
    stroke: '#DC2626'
    strokeWidth: 6
    gap: 40
  number:
    radius: 26
    size: 40
    fill: '#DC2626'
    text: '#FFFFFF'
  mask:
    fill: '#94A3B8'
```

| Key | Applies to |
| --- | --- |
| `color` | Boxes, arrows and discs |
| `canvas` | Space added around the image for labels |
| `box.width`, `box.radius`, `box.pad` | The outline drawn around a mark |
| `arrow.shaft`, `arrow.headHalf`, `arrow.headLength` | The arrow from a label to a box |
| `label.font`, `label.weight`, `label.size` | Label typeface |
| `label.fill`, `label.stroke`, `label.strokeWidth` | Label glyphs and their outline |
| `label.gap` | Distance from the label to the box |
| `label.fontUrl` | Stylesheet or font file to load before drawing |
| `number.radius`, `number.size` | Numbered disc and its numeral |
| `number.fill`, `number.text` | Disc color and numeral color |
| `mask.fill` | What a masked region is painted with |

`label.stroke` and `number.fill` default to `color`. `strokeWidth` is centered on the glyph outline, so half of it is hidden under the fill.

Written by Nicola Mustone · Applies to shotlist 0.6.0 · Maintained by Nicola Mustone

Published date unavailable · Updated date unavailable · [View source](https://github.com/SirDarcanos/shotlist.dev/blob/main/src/pages/docs/reference/configuration.astro) · [Propose a correction](https://github.com/SirDarcanos/shotlist.dev/edit/main/src/pages/docs/reference/configuration.astro)