Configuration and commands · Docs

Every vdiff.config.json option, every command, and where visualdiff keeps its data.

Config#

vdiff.config.json lives in the site's repo. Setup writes it; edit it in Advanced during setup, or in your editor.

{
  "project": "acme",                            // name of the project's folder in ~/.vdiff
  "environments": {
    "before": { "sites": { "default": "https://acme-c3.test/", "french": "https://acme-c3-fr.test/" } },
    "after":  { "sites": { "default": "https://acme-c4.test/", "french": "https://acme-c4-fr.test/" },
                "headers": {}, "httpCredentials": null }
  },
  "pages": {
    "craft": {                                  // or wordpress, statamic, filament, laravel, sitemap: see Page sources
      "alwaysAll": ["builder"],                 // groups where every page is taken
      "perGroup": { "default": 3, "*": 1 },     // pages per group, by site
      "exclude": ["errorNotFound"]
    },
    "static": ["/", "does-not-exist-404"],      // extra pages: /path, site:/path or a full URL
    "exclude": ["^account/"],                   // regular expressions on the path
    "limit": null
  },
  "viewports": [
    { "name": "desktop", "width": 1440, "height": 900 },
    { "name": "mobile", "width": 390, "height": 844, "isMobile": true }
  ],
  "threshold": 24,                              // colour difference above which a pixel counts as changed
  "concurrency": 6,                             // browser tabs per side
  "retries": 2,                                 // extra attempts after a network blip or timeout
  "timeout": 90000,                             // ms per page
  "hideSelectors": ["#CybotCookiebotDialog"],   // hidden before every screenshot
  "blockHosts": ["widget.example.com"],         // added to the built-in tracker list
  "blockDefaultHosts": true,
  "settleMs": 250,                              // pause after the network goes quiet, before the screenshot
  "reuseBaseline": false,                       // reuse the latest before run by default
  "errorTitlePattern": "…", "errorBodyPattern": "…",  // what counts as an error page ("" turns it off)
  "api": { "ignore": ["updated_at"] },          // data fields to leave out of comparisons
  "login": null,                                // automatic sign-in: see Page sources
  "session": "out",                             // "in" to compare signed in by default
  "branches": { "serve": "auto", "database": { "mode": "clone" } }   // see Compare git branches
}

Pages are matched across runs by site and path, so the same page pairs up in any two comparisons.

Commands#

The vdiff command comes with the app: Install command-line tool… in the visualdiff menu. Run vdiff on its own for the list of commands, and vdiff <command> --help for one command's arguments, options and examples. At a terminal, missing arguments are asked for: pick the environments or branches to compare from a list.

Command	Does
`vdiff init [--before URL] [--after URL]`	Set up the project in the current folder
`vdiff urls [--full]`	Show the pages a comparison would capture
`vdiff compare <A> <B>`	Capture and compare two environments or branches. `--full`, `--page REF`, `--limit N`, `--reuse-before`, `--fresh-db`
`vdiff compare <A> <B> --failed --into-a RUN --into-b RUN`	Re-capture only the failed pages of a comparison
`vdiff check <urlA> <urlB>`	Quick check: compare two URLs without a project
`vdiff shoot <env>`	Capture one environment
`vdiff diff <runA> <runB>`	Compare two existing runs
`vdiff export <A> <B> [--format md\|csv] [--out FILE] [--all]`	The upgrade report
`vdiff branch:up <ref>`, `branch:down`, `branch:list`, `branch:serve`	Prepare, remove, list or serve branch environments (`--drop-db`)
`vdiff login <env>`, `vdiff logout <env>`	Save or forget an environment's sign-in
`vdiff runs`	List runs
`vdiff license`, `license:login`, `license:activate`, `license:refresh`, `license:logout`	Your licence on this Mac
`vdiff serve [--port 4400]`	The app's interface in your browser, plus MCP at `/mcp`
`vdiff mcp`	MCP over stdio

Runs are named after their environment, so vdiff compare before after and vdiff export before after refer to the newest runs of each.

Where things live#

~/.vdiff/
  license.json                       your licence on this Mac
  projects.json                      known projects and their config files
  <project>/
    pages.json                       the page list
    branches.json                    prepared branches
    auth/<env>.json                  saved signed-in sessions
    runs/<time>-<label>/             screenshots and a manifest
    diffs/<runA>__vs__<runB>/        difference images, results and reviews

Full-page screenshots add up: delete old run folders when you're done with a project. VDIFF_HOME=/path moves everything.