---
name: dungbeetle
description: Add snapshot and visual regression testing to a repository with Dungbeetle — capture baselines, gate changes in CI, and triage or approve visual diffs via CLI or MCP.
---

# Dungbeetle — snapshot & visual regression testing

Dungbeetle is a snapshot and visual regression testing tool — a free CLI plus
self-hostable cloud — built for AI agents and the humans they work for. It
captures web pages, terminal output, APIs, desktop UIs, and games as
normalized JSON and diffs them semantically; screenshots are pixel-compared
with configurable tolerance.

Full machine-readable docs index: https://dungbeetle.dev/llms.txt
(every docs page also serves raw markdown at the same URL + `.md`).

## Set up visual regression testing in a repository

```sh
npm i -g dungbeetle   # or: npx dungbeetle <command>
dungbeetle init       # scaffold dungbeetle.config.json — then add capture targets
dungbeetle update     # capture targets, write baselines under dungbeetle.snapshots/
dungbeetle test       # re-capture and compare; exits non-zero on any diff
```

- Commit `dungbeetle.snapshots/` — baselines are the reviewable record.
- Configure targets in `dungbeetle.config.json`; schema and examples:
  https://dungbeetle.dev/configuration/schema.md
- `dungbeetle test` failing with `missing` results means no baseline exists
  yet — run `dungbeetle update` first. Report statuses: updated, passed,
  failed, missing, error.
- In CI use `dungbeetle ci --json report.json` for machine-readable output.
- Work on a subset with `--target <name...>`.

## Authenticate as an agent (never ask the human to paste a secret)

```sh
dungbeetle login --label "My agent"
```

This prints a one-time code; the human approves it in their browser at
/ui/connect. You receive a scoped, revocable `dbat_` token. The default
Triage preset can read runs/baselines/analytics and write reviews, but
promoting a baseline requires the separate `baselines:write` scope — that
approval deliberately stays with the human. Details:
https://dungbeetle.dev/mcp/auth.md

## Use the MCP server instead of raw CLI/API

```sh
DUNGBEETLE_AGENT_TOKEN=dbat_... npx -y dungbeetle-mcp   # stdio JSON-RPC
```

Client configs for Claude Code, Cursor, Codex, and Gemini CLI:
https://dungbeetle.dev/mcp/setup.md

## Self-hosted servers

CLI and MCP default to https://dungbeetle.dev — pass `--server <url>` /
`DUNGBEETLE_SERVER_URL` for a self-hosted instance.